https://github.com/andydecleyre/mouse-ran-down
Bring videos from shared X/Reddit/Instagram/TikTok/Bluesky links directly into Telegram chats.
https://github.com/andydecleyre/mouse-ran-down
bluesky instagram reddit telegram telegram-bot tiktok twitter
Last synced: 8 months ago
JSON representation
Bring videos from shared X/Reddit/Instagram/TikTok/Bluesky links directly into Telegram chats.
- Host: GitHub
- URL: https://github.com/andydecleyre/mouse-ran-down
- Owner: AndydeCleyre
- License: unlicense
- Created: 2024-11-26T19:27:20.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-18T22:20:20.000Z (over 1 year ago)
- Last Synced: 2025-02-18T22:31:41.204Z (over 1 year ago)
- Topics: bluesky, instagram, reddit, telegram, telegram-bot, tiktok, twitter
- Language: Python
- Homepage:
- Size: 71.3 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Mouse Ran Down
[](https://github.com/andydecleyre/mouse-ran-down/actions/workflows/fmt_lint.yml)
[](https://ghcr.io/andydecleyre/mouse-ran-down)
[](https://github.com/andydecleyre/mouse-ran-down/actions/workflows/reqs.yml)
[](https://pypi.org/project/mouse_ran_down/)
This is a Telegram bot.
When added to a group, any shared public
X/Reddit/Instagram/TikTok/Bluesky/YouTube/Vimeo/SoundCloud/Bandcamp/Mastodon
posts with media will be replied to with the media
uploaded directly into the chat, along with a preview image.
You can also send links as direct (or forwarded) messages to the bot.
If you have Telegram Premium or a Business account,
you can add the bot to any or all of your one-on-one chats, as well.
In that case, it will look to the other party as if you personally sent the media.
Normally, entire accounts, playlists, and albums won't be loaded.
You can insist that the bot try to load a link by including
the bot's name in the same message (e.g. `@MouseRanDownBot`).
Currently running at [@MouseRanDownBot](https://t.me/MouseRanDownBot).
I do not guarantee any level of service or privacy, so I encourage you to run it yourself.
## Credentials
Copy `credentials.example.nt` to `credentials.nt` and insert at least a Telegram bot token.
Comment out, delete, or use empty values for any unused fields.
### Telegram
Use Telegram's [@BotFather](https://t.me/BotFather) to create a bot and get its token.
Ensure you give it permission to read group messages by disabling privacy mode.
### Cookies
The optional cookies entry helps if using the bot for reddit video links,
and age-restricted content and such on other platforms.
You can get the cookie content in the right format with `yt-dlp`'s
`--cookies` and `--cookies-from-browser` options,
or a browser extension like [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/)
(I can't vouch for the security of this or any extension).
## Installing directly
You can use `pip`/`pipx`/`uv`/`zpy` etc. to install the package from PyPI, e.g.:
```console
$ uv tool install mouse-ran-down
$ uv tool install 'mouse-ran-down[sentry]' # for Sentry/GlitchTip integration
```
To run it effectively you'll need to install `ffmpeg` and `mailcap`,
and you might benefit from installing `atomicparsley`.
Run `mouse-ran-down --help` for usage.
You may prefer to just use the container image from my registry (see below).
## Build the container image
Make container image with `./mk/ctnr.sh`:
```console
$ ./mk/ctnr.sh -h
Build a container image for Mouse Ran Down
Usage: ./mk/ctnr.sh [--connect-repo URL] []
defaults to ghcr.io/andydecleyre/mouse-ran-down
```
## Run the container
If doing any of these for a rootless container on a Systemd-using server,
don't forget to run this once:
```console
$ loginctl enable-linger
```
Otherwise podman will kill the container on logout.
### From a local image
Run the container from a local image `ghcr.io/andydecleyre/mouse-ran-down` with:
```console
$ podman run --rm -d -v ./credentials.nt:/app/credentials.nt:ro ghcr.io/andydecleyre/mouse-ran-down
```
### From an image pushed to a registry
`./start/podman.sh`:
```console
$ ./start/podman.sh -h
Usage: ./start/podman.sh [-n ] [-i ] [-t ] [-c] []
-n : name of the container (default: mouse)
-i : name of the image (default: ghcr.io/andydecleyre/mouse-ran-down)
-t : tag of the image (default: main)
-c: remove any dangling images after starting the container
: path to credentials.nt (default: ./credentials.nt)
```
### As an auto-updating Systemd service, pulling from a registry
Or you could write an auto-update-friendly quadlet systemd service at
`~/.config/containers/systemd/mouse.container`, changing the values as you like:
```ini
[Container]
AutoUpdate=registry
ContainerName=mouse
Image=ghcr.io/andydecleyre/mouse-ran-down:main
Volume=%h/mouse-ran-down/credentials.nt:/app/credentials.nt:ro
[Service]
Restart=always
TimeoutStartSec=120
[Install]
WantedBy=default.target
```
Ensure the service is discovered/generated, and start it:
```console
$ systemctl --user daemon-reload
$ systemctl --user start mouse
```
Ensure the auto-updating timer is enabled:
```console
$ systemctl --user enable --now podman-auto-update.timer
```
## View container logs
```console
$ podman logs CONTAINER_NAME # e.g. mouse
```