https://github.com/machineonamission/mediaforge
A Discord bot for editing and creating videos, images, GIFs, and more!
https://github.com/machineonamission/mediaforge
bot discord discord-py ffmpeg fun gifs libvips meme python
Last synced: 5 months ago
JSON representation
A Discord bot for editing and creating videos, images, GIFs, and more!
- Host: GitHub
- URL: https://github.com/machineonamission/mediaforge
- Owner: machineonamission
- License: agpl-3.0
- Created: 2020-11-23T23:06:14.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2026-01-12T02:14:59.000Z (5 months ago)
- Last Synced: 2026-01-12T07:35:57.819Z (5 months ago)
- Topics: bot, discord, discord-py, ffmpeg, fun, gifs, libvips, meme, python
- Language: Python
- Homepage: https://discord.com/oauth2/authorize?client_id=780570413767983122
- Size: 127 MB
- Stars: 93
- Watchers: 7
- Forks: 31
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
# [Invite MediaForge!](https://discord.com/oauth2/authorize?client_id=780570413767983122)
[](https://top.gg/bot/780570413767983122)
[](https://wakatime.com/@machineonamission/projects/ttvriomkzo)
[](https://github.com/machineonamission/mediaforge/stargazers)
[](https://uptime.statuscake.com/?TestID=JyWrfGfIjT)
[](https://discord.gg/xwWjgyVqBz)
[](https://knowyourmeme.com/memes/trollface)
[](https://ko-fi.com/Q5Q75US4A)
### A Discord bot for editing and creating videos, images, GIFs, and more!
## general technical info about the bot
- inspired by [esmBot](https://github.com/esmBot/esmBot)
- uses discord.py 2
- uses libvips for captioning
- uses FFmpeg for media processing
## self-host with docker
### to install
as of writing, a working docker copy of MediaForge takes up ~3.46GB. if this is a concern and you are using some of the
apt libraries MediaForge does, see [to self-host natively](#to-self-host-natively)
All you need to install yourself is [Docker Desktop](https://docs.docker.com/get-docker/)
once that's installed, run these commands in your terminal of choice.
```shell
docker build -t machineonamission/mediaforge https://github.com/machineonamission/mediaforge.git
docker run -it --cap-add SYS_NICE --name mediaforge machineonamission/mediaforge
```
on linux, you may need to run docker with `sudo`
if the installation succeeded, you should be prompted with some options. you'll need to select "Edit Config". this will
open a text editor within your terminal. the 1 required config setting to change for proper functionality is the
[discord token](https://github.com/reactiflux/discord-irc/wiki/creating-a-discord-bot-&-getting-a-token). be sure not to
add or remove quotes. press `CTRL+S` to save and `CTRL+X` to exit.
if you don't want to use the built-in text editor, you can [get the example config from GitHub](config.example.py), hold
down `CTRL+K` to clear the file and then use `CTRL+V` to paste in your config.
### to run
run in your favorite terminal:
```shell
docker start -ia mediaforge
```
by default, MediaForge will await user input for 10 seconds before attempting to run the bot automatically.
### to stop
killing the terminal window/`CTRL+C` won't kill the bot, because docker runs in the background.
to stop the bot, run
```shell
docker stop mediaforge
```
if the bot refuses to stop for some reason, you can run
```shell
docker kill mediaforge
```
to forcibly kill it.
### to limit resource consumption
since docker is very containerized, you can easily limit the amount of resources it's allowed to consume.
the main command to do this is [`docker update`](https://docs.docker.com/engine/reference/commandline/update/#usage),
though most of these arguments can be passed verbatim to `docker run` during setup.
the most useful options are `--memory` and `--cpus`.
for example, this is (as of writing) what the official MediaForge bot uses:
```shell
docker update --memory 9000M --memory-swap -1 --cpus "3.9" mediaforge
```
- `--memory 9000M`: this limits it to 9gb (9000mb) of physical memory
- `--memory-swap -1`: this allows it to use as much swap memory as it wants (swap memory is temporarily storing memory
on disk)
- `--cpus "3.9"`: the host server has 4 cores, so this allows it to use "3.9"/4 (97.5%) of the PC's CPU time.
### Automode
this is designed to work with hosting providers where terminal control is not possible. There are 3 arguments to this
mode that can be set as
docker [build arguments](https://docs.docker.com/engine/reference/commandline/build/#build-arg)
or [environment variables](https://docs.docker.com/engine/reference/commandline/run/#env)
.
`AUTOMODE`: set to "ON" to enable automode
`AUTOUPDATE`: set to "ON" to update code and packages every run
`CONFIG`: base64 encoded version of your config file.
#### to encode base 64
##### on linux:
- `base64 config.py` prints the output to terminal
- `base64 config.py > config.txt` writes the output to `config.txt`
##### with python:
```python
import base64
with open("config.py", "rb") as f:
out = base64.b64encode(f.read())
print(out) # write to terminal
# write to file
with open("config.txt", "wb+") as f:
f.write(out)
```
## to self-host natively
MediaForge is a complex application and manually installing all dependencies is a headache. for almost all use
cases, [the docker distribution](#self-host-with-docker) is much better.
### summary
ensure your OS is one of the [supported OSes](#supported-oses), then install the [python libraries](#python-libraries)
and the [non-python libraries](#non-python-libraries), set up the [config](#config), and [run](#to-run)
### supported OSes
built and tested on windows 11 and debian bookworm (inside docker). these 2 OSes (and their successors) will
continue to be officially supported.
MediaForge only has official support for x86_64, but ARM64 seems to work fine
will _probably_ work on macos and other linux/unix distros if the below libraries are available but theyre untested and
unsupported. just replace `apt-get` with your system's preferred package manager ([`brew`](https://brew.sh/) for macos)
on Windows, color emojis won't work. no idea why, just is a windows pango bug.
### python libraries
- MediaForge depends on Python ≥3.11. `uv` will install it automatically.
- This project uses [`uv`](https://github.com/astral-sh/uv), which will automatically install python and dependencies on
run.
- install `uv` with [these instructions](https://docs.astral.sh/uv/getting-started/installation/) (varies per
system)
- part of [`pyvips`](https://pypi.org/project/pyvips/) is built from source on installation.
- on Windows this will require the MSVC compiler, which is an optional component
of [Visual Studio](https://visualstudio.microsoft.com/downloads/)
- on Linux this will require [`gcc`](https://packages.ubuntu.com/bionic/gcc), installable
by `sudo apt-get install gcc`
### non-python libraries
the bot uses many external CLI programs for media processing.
- FFmpeg - not included but [easily installable on windows and linux](https://ffmpeg.org/download.html)
- **If installing on linux, ensure that ffmpeg version >= 5**
- libvips - installable on linux with `sudo apt-get install libvips-dev`
. [windows instructions here](https://www.libvips.org/install.html#installing-the-windows-binary)
- ImageMagick - **not included** but [downloadable here](https://imagemagick.org/script/download.php)
- TTS
- on linux, this uses [`mimic`](https://github.com/MycroftAI/mimic1). a pre-compiled binary is included.
- the male and female voices are downloaded from mimic's repo on bot start if they are not detected. if you want
to re-download for some reason, delete the 2 files ending in `.flitefox` in `tts/`
- on windows, [`powershell`](https://aka.ms/powershell) is used to
access [Windows's native TTS](https://docs.microsoft.com/en-us/uwp/api/windows.media.speechsynthesis.speechsynthesizer)
. Both are included in modern versions of Windows, but ensure powershell is in the system path.
- deno - [deno](https://deno.com/)
- if you're curious, it's used for the retro TTS and yt-dlp's bgpot plugin
### config
- create a copy of [`config.example.py`](config.example.py) and name it `config.py`.
- insert/change the appropriate config settings such as your discord api token. be sure not to add or remove quotes.
- the 2 required config settings to change for proper functionality are the discord and tenor tokens.
### python
- developed and tested on python 3.11. use that or a later compatible version
### to run
- once you've set up all of the libraries, just run the program with `uv run python src/main.py` make sure it can read
and write to the
directory it lives in and also access/execute all the aforementioned libraries
- terminate the bot by running the `shutdown` command, this will _probably_ close better than a termination
## legal stuff
[terms of service](media/external/terms_of_service.md)
[privacy policy](media/external/privacy_policy.md)