# How to Contribute to RedditVideoMakerBot: A Developer's Guide

> Learn how to contribute to RedditVideoMakerBot. Fork the repo, set up your environment, and submit a pull request. Your guide to developing for this popular Reddit bot.

- Repository: [Lewis Menelaws/RedditVideoMakerBot](https://github.com/elebumm/RedditVideoMakerBot)
- Tags: how-to-guide
- Published: 2026-04-08

---

**To contribute to RedditVideoMakerBot, fork the repository, create a feature branch from `develop`, install dependencies via `pip install -r requirements.txt`, ensure your code is Python 3.10+ compatible, and submit a pull request with descriptive commit messages following the `type: explanation` format.**

RedditVideoMakerBot is a Python-based CLI tool that automatically converts Reddit threads into short videos using ffmpeg, Playwright, and various TTS engines. Whether you want to add a new voice provider, fix screenshot capture issues, or improve the configuration system, understanding the codebase structure in `elebumm/RedditVideoMakerBot` will help you make effective contributions.

## Understanding the Architecture

The bot follows a layered pipeline architecture orchestrated by [`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py). Each layer handles a specific responsibility in the video generation process.

The execution flow in [`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py) proceeds through these stages:

1. **Configuration Loading** — `settings.check_toml()` in [`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py) validates and loads user settings from the TOML configuration file.
2. **Data Fetching** — `get_subreddit_threads()` retrieves thread JSON data via praw.
3. **Audio Generation** — `save_text_to_mp3()` in [`video_creation/voices.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/voices.py) converts text to speech using the selected engine.
4. **Visual Capture** — `get_screenshots_of_reddit_posts()` in [`video_creation/screenshot_downloader.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/screenshot_downloader.py) captures Reddit post screenshots using Playwright.
5. **Background Preparation** — Functions in [`video_creation/background.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/background.py) download and trim background media.
6. **Final Assembly** — `make_final_video()` in [`video_creation/final_video.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/final_video.py) stitches everything together with ffmpeg.

Key modules include:

- **[`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py)** — CLI entry point that validates Python version, installs ffmpeg, and orchestrates the pipeline.
- **[`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py)** — Loads the TOML template, prompts for missing values, and writes [`config.toml`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/config.toml).
- **[`utils/console.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/console.py)** — Provides Rich-styled console output and interactive prompts used throughout the tool.
- **[`video_creation/voices.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/voices.py)** — Handles TTS conversion for titles and comments.
- **[`video_creation/screenshot_downloader.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/screenshot_downloader.py)** — Manages Reddit screenshot capture via Playwright.
- **[`video_creation/background.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/background.py)** — Downloads, trims, and applies fade effects to background video/audio.
- **[`video_creation/final_video.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/final_video.py)** — Uses ffmpeg to composite voice tracks, screenshots, and background into the final MP4.

## Setting Up Your Development Environment

Before writing code, ensure you can run the bot locally:

1. **Fork and clone** the repository from GitHub.
2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Verify the setup** by running `python main.py` to ensure the current codebase works on your machine.

The project requires **Python 3.10 or higher**. The [`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py) entry point includes version checking logic to enforce this requirement.

## The Contribution Workflow

RedditVideoMakerBot follows a standard GitHub workflow defined in [`CONTRIBUTING.md`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/CONTRIBUTING.md). Follow these steps to ensure your contribution is accepted:

1. **Create a branch** off the `develop` branch (the project's default development branch, not `master`).
2. **Write Python 3.10+ compatible code** following the existing style guide.
3. **Use conventional commit messages** in the format `type: explanation` (e.g., `feat: add ElevenLabs voice support`).
4. **Update configuration validation** in [`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py) if you add new settings to the TOML template.
5. **Test locally** by running `python main.py` and verifying the video output matches expectations.
6. **Open a pull request** targeting the `develop` branch.
   - Include "Fixes #<issue-number>" if your PR resolves an existing issue.
   - Keep the PR description concise but explain the motivation behind the change.

## Common Contribution Examples

### Adding a New TTS Engine

To integrate a new text-to-speech provider like *AcmeTTS*, modify [`video_creation/voices.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/voices.py):

```python

# video_creation/voices.py

from TTS.acme_tts import AcmeEngine   # new import

def save_text_to_mp3(reddit_object):
    tts_choice = settings.config["settings"]["tts"]["voice_choice"]
    if tts_choice == "acme":
        engine = AcmeEngine(api_key=settings.config["settings"]["tts"]["acme_api_key"])
        # Use engine.synthesize(text) to produce .mp3 files

    # existing branches...

```

Then update [`utils/.config.template.toml`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/.config.template.toml) with the new `acme_api_key` field and ensure `settings.check_toml()` validates it.

### Changing the Background Video Source

To allow custom YouTube URLs for backgrounds, modify [`video_creation/background.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/background.py):

```python

# video_creation/background.py

def get_background_config(kind: str) -> dict:
    if kind == "video" and config["background"]["custom_youtube"]:
        return {"type": "youtube", "url": config["background"]["custom_youtube"]}
    # fall back to default

```

Add `custom_youtube` to the TOML template and implement URL validation in [`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py).

### Running the Tool for Single Post Testing

Test specific posts without modifying [`config.toml`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/config.toml):

```bash

# Process a specific post ID directly

python main.py abcdef

```

This bypasses the config file and processes only the specified post ID. Use the console helpers in [`utils/console.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/console.py) (`print_step`, `print_substep`) to track progress during debugging.

## Summary

- **Target the `develop` branch** for all pull requests, not `master`.
- **Maintain Python 3.10+ compatibility** and use `type: description` commit formats.
- **Update [`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py)** whenever adding new configuration options to the TOML template.
- **Test with `python main.py <post_id>`** to verify changes produce valid video output.
- **Reference [`CONTRIBUTING.md`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/CONTRIBUTING.md)** for detailed bug reporting and enhancement suggestion templates.

## Frequently Asked Questions

### Which branch should I target for pull requests?

Always target the `develop` branch. RedditVideoMakerBot uses `develop` as the default integration branch where features are tested before merging to `master`. Creating branches off `develop` prevents merge conflicts with ongoing development work.

### What Python version is required to contribute?

The codebase requires **Python 3.10 or higher**. The [`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py) entry point explicitly checks the Python version on startup and exits with an error if running on older versions, ensuring compatibility with modern type hints and syntax used throughout the project.

### How do I add new configuration options?

Add the field to [`utils/.config.template.toml`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/.config.template.toml), then update [`utils/settings.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/utils/settings.py) to include validation logic in `check_toml()`. The settings module uses this validation to prompt users for missing values and ensure data types (strings, integers, URLs) are correct before the bot executes.

### Where should I implement a new screenshot capture method?

Screenshot logic belongs in [`video_creation/screenshot_downloader.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/video_creation/screenshot_downloader.py), which uses Playwright to capture Reddit posts. If your method requires new dependencies or browser configurations, ensure they are handled gracefully in the setup phase within [`main.py`](https://github.com/elebumm/RedditVideoMakerBot/blob/main/main.py) and documented in your pull request.