2023-04-25 12:40:54 +00:00
|
|
|
# slidge-whatsapp
|
|
|
|
|
|
2023-06-23 21:15:39 +00:00
|
|
|
[Home](https://sr.ht/~nicoco/slidge) |
|
|
|
|
|
[Docs](https://slidge.im/slidge-whatsapp) |
|
2023-08-12 05:34:08 +00:00
|
|
|
[Issues](https://todo.sr.ht/~nicoco/slidge-whatsapp) |
|
2023-06-23 21:15:39 +00:00
|
|
|
[Patches](https://lists.sr.ht/~nicoco/public-inbox) |
|
|
|
|
|
[Chat](xmpp:slidge@conference.nicoco.fr?join)
|
|
|
|
|
|
2023-04-25 12:40:54 +00:00
|
|
|
A
|
|
|
|
|
[feature-rich](https://slidge.im/slidge-whatsapp/features.html)
|
2023-06-23 21:15:39 +00:00
|
|
|
[WhatsApp](https://whatsapp.com) to
|
2023-04-25 12:40:54 +00:00
|
|
|
[XMPP](https://xmpp.org/) puppeteering
|
|
|
|
|
[gateway](https://xmpp.org/extensions/xep-0100.html), based on
|
|
|
|
|
[slidge](https://slidge.im) and
|
|
|
|
|
[whatsmeow](https://github.com/tulir/whatsmeow).
|
|
|
|
|
|
|
|
|
|
[](https://builds.sr.ht/~nicoco/slidge-whatsapp/commits/master/ci.yml)
|
|
|
|
|
[](https://builds.sr.ht/~nicoco/slidge-whatsapp/commits/master/container.yml)
|
|
|
|
|
[](https://pypi.org/project/slidge-whatsapp/)
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
Refer to the [slidge admin documentation](https://slidge.im/core/admin/)
|
|
|
|
|
for general info on how to set up an XMPP server component.
|
|
|
|
|
|
|
|
|
|
### Containers
|
|
|
|
|
|
|
|
|
|
From [dockerhub](https://hub.docker.com/r/nicocool84/slidge-whatsapp)
|
|
|
|
|
|
|
|
|
|
```sh
|
2024-02-17 13:50:01 +00:00
|
|
|
# use ravermeister/slidge-whatsapp for arm64 (thanks raver! <3)
|
2023-04-25 12:40:54 +00:00
|
|
|
docker run docker.io/nicocool84/slidge-whatsapp
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Python package
|
|
|
|
|
|
|
|
|
|
With [pipx](https://pypa.github.io/pipx/):
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
2023-09-28 20:12:22 +00:00
|
|
|
# for the latest stable release (if any)
|
|
|
|
|
pipx install slidge-whatsapp
|
2023-04-25 12:40:54 +00:00
|
|
|
|
2023-09-28 20:12:22 +00:00
|
|
|
# for the bleeding edge
|
|
|
|
|
pipx install slidge-whatsapp \
|
|
|
|
|
--pip-args='--extra-index-url https://slidge.im/repo'
|
Implement on-the-fly outgoing media conversion
WhatsApp clients are set to accept only a specific set of media files as
image, audio, or video messages, specifically:
- Images must be in JPEG (non-progressive) format.
- Audio messages must be in Opus-encoded Ogg if sent as voice messages,
otherwise may be in MP3 or AAC format if not (though client support
may vary).
- Video messages must be in h264-encoded MP4, with some additional
constraints on color format and profile used.
Several edge-cases exist, e.g. with GIF files needing to be re-encoded
as MP4 in order to be animated (and requiring extra metadata in messages
to be called out as such).
This commit implements a somewhat comprehensive media conversion scheme,
built upon FFmpeg for audio and video, and native Go facilities for
images, based on the source format. Specifically:
- Audio files in `audio/mp4` or `audio/aac` format (corresponding to
formats commonly used in Android and iOS XMPP clients, respectively)
are automatically re-encoded as Opus-encoded voice messages.
- Audio files in `audio/mpeg` (i.e. MP3 files) or `audio/ogg` format
are sent as plain audio files in their own format, with varying client
support assumed.
- Images in `image/png` or `image/webp` format are automatically
re-encoded as JPEG image messages. Conversely, images in `image/gif`
format are re-encoded as MP4 video messages with auto-play enabled.
- Videos in `video/webm` or `video/mp4` format are automatically
re-encoded as MP4 video messages (the latter is re-encoded to ensure
option compatibility).
As stated above, all audio and video conversions require FFmpeg and
FFprobe to be installed, and, if missing, will leave attachments
unchanged (which may result these being sent as binary files). Image
conversions do not rely on any external functionality, however.
Current limits are: 10MiB for images and 20MiB for audio and video
files; above these conversions will fail and original files will be sent
instead.
Future commits may see compatibility improved, or semantics corrected
where these do not match expectations on the WhatsApp side.
2023-07-17 21:21:31 +00:00
|
|
|
|
2023-09-28 20:12:22 +00:00
|
|
|
slidge-whatsapp --help
|
Implement on-the-fly outgoing media conversion
WhatsApp clients are set to accept only a specific set of media files as
image, audio, or video messages, specifically:
- Images must be in JPEG (non-progressive) format.
- Audio messages must be in Opus-encoded Ogg if sent as voice messages,
otherwise may be in MP3 or AAC format if not (though client support
may vary).
- Video messages must be in h264-encoded MP4, with some additional
constraints on color format and profile used.
Several edge-cases exist, e.g. with GIF files needing to be re-encoded
as MP4 in order to be animated (and requiring extra metadata in messages
to be called out as such).
This commit implements a somewhat comprehensive media conversion scheme,
built upon FFmpeg for audio and video, and native Go facilities for
images, based on the source format. Specifically:
- Audio files in `audio/mp4` or `audio/aac` format (corresponding to
formats commonly used in Android and iOS XMPP clients, respectively)
are automatically re-encoded as Opus-encoded voice messages.
- Audio files in `audio/mpeg` (i.e. MP3 files) or `audio/ogg` format
are sent as plain audio files in their own format, with varying client
support assumed.
- Images in `image/png` or `image/webp` format are automatically
re-encoded as JPEG image messages. Conversely, images in `image/gif`
format are re-encoded as MP4 video messages with auto-play enabled.
- Videos in `video/webm` or `video/mp4` format are automatically
re-encoded as MP4 video messages (the latter is re-encoded to ensure
option compatibility).
As stated above, all audio and video conversions require FFmpeg and
FFprobe to be installed, and, if missing, will leave attachments
unchanged (which may result these being sent as binary files). Image
conversions do not rely on any external functionality, however.
Current limits are: 10MiB for images and 20MiB for audio and video
files; above these conversions will fail and original files will be sent
instead.
Future commits may see compatibility improved, or semantics corrected
where these do not match expectations on the WhatsApp side.
2023-07-17 21:21:31 +00:00
|
|
|
```
|
|
|
|
|
|
2023-09-30 12:12:43 +00:00
|
|
|
Make sure to install `ffmpeg` for full outgoing media compatibility; for
|
|
|
|
|
example, in Debian/Ubuntu:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
sudo apt install ffmpeg
|
|
|
|
|
```
|
|
|
|
|
|
2023-04-25 12:40:54 +00:00
|
|
|
## Dev
|
|
|
|
|
|
|
|
|
|
```sh
|
2023-09-30 12:12:43 +00:00
|
|
|
git clone https://git.sr.ht/~nicoco/slidge
|
2023-04-25 12:40:54 +00:00
|
|
|
git clone https://git.sr.ht/~nicoco/slidge-whatsapp
|
|
|
|
|
cd slidge-whatsapp
|
|
|
|
|
docker-compose up
|
|
|
|
|
```
|
