How to Contribute to RedditVideoMakerBot: A Developer's Guide

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. Each layer handles a specific responsibility in the video generation process.

The execution flow in main.py proceeds through these stages:

1. Configuration Loading — settings.check_toml() in 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 converts text to speech using the selected engine.
4. Visual Capture — get_screenshots_of_reddit_posts() in video_creation/screenshot_downloader.py captures Reddit post screenshots using Playwright.
5. Background Preparation — Functions in video_creation/background.py download and trim background media.
6. Final Assembly — make_final_video() in video_creation/final_video.py stitches everything together with ffmpeg.

Key modules include:

• main.py — CLI entry point that validates Python version, installs ffmpeg, and orchestrates the pipeline.
• utils/settings.py — Loads the TOML template, prompts for missing values, and writes config.toml.
• utils/console.py — Provides Rich-styled console output and interactive prompts used throughout the tool.
• video_creation/voices.py — Handles TTS conversion for titles and comments.
• video_creation/screenshot_downloader.py — Manages Reddit screenshot capture via Playwright.
• video_creation/background.py — Downloads, trims, and applies fade effects to background video/audio.
• 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:

   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 entry point includes version checking logic to enforce this requirement.

The Contribution Workflow

RedditVideoMakerBot follows a standard GitHub workflow defined in 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 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 #" 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:

# 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 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:

# 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.

Running the Tool for Single Post Testing

Test specific posts without modifying config.toml:

# 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 (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 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 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 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, then update 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, 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 and documented in your pull request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}