Contributing

Thank you for your interest in contributing to ffmpeg-normalize! This guide will help you get started.

Getting Started

Prerequisites

Python 3.9 or higher
FFmpeg installed and available in PATH
uv (recommended) or pip

Setting Up Your Development Environment

Fork and clone the repository

git clone https://github.com/YOUR-USERNAME/ffmpeg-normalize.git
cd ffmpeg-normalize

Install dependencies

Using uv (recommended):
```
uv sync --group dev
```
Or using pip:
```
pip install -e ".[dev]"
```

Verify your setup

# Run tests
uv run pytest

# Run the tool
uv run python -m ffmpeg_normalize --help

Development Workflow

Making Changes

Create a new branch from master

git checkout -b feature/your-feature-name

Make your changes following the code style guidelines below
Run tests to ensure everything works
```
uv run pytest
```

Check code quality

# Linting
uv run ruff check .

# Code formatting
uv run ruff format .

# Type checking
uv run mypy src/ffmpeg_normalize

Commit Guidelines

We use Conventional Commits for commit messages. Each commit message should follow this format:

<type>: <description>

[optional body]

[optional footer]

Types: - feat: — New feature - fix: — Bug fix - docs: — Documentation changes - test: — Adding or updating tests - refactor: — Code refactoring - chore: — Maintenance tasks

Examples:

git commit -m "feat: add selective audio stream normalization"
git commit -m "fix: apply extra input options to first pass"
git commit -m "docs: update contributing guide"

Submitting a Pull Request

Push your changes to your fork

git push origin feature/your-feature-name

Create a pull request on GitHub
- Provide a clear title and description
- Reference any related issues
- Ensure all tests pass
- Request review from maintainers

Code Guidelines

Project Structure

src/ffmpeg_normalize/ — Main package directory
_ffmpeg_normalize.py — Main orchestration class
_media_file.py — Media file representation
_streams.py — Stream classes (Audio, Video, Subtitle)
_cmd_utils.py — FFmpeg command utilities
_errors.py — Custom exceptions
_logger.py — Logging configuration
tests/ — Test files and test media samples
docs/ — MKdocs documentation source

Testing

Tests use pytest and include actual media files in tests/
Tests call the CLI directly using python -m ffmpeg_normalize to test the full pipeline
Always add tests for new features
Ensure existing tests pass before submitting PR

Code Style

Follow PEP 8 guidelines
Use type hints where applicable
Run ruff format before committing
Ensure mypy passes without errors

Development Commands Reference

Testing

uv run pytest                              # Run all tests
uv run pytest tests/test_all.py -v        # Run specific test file
uv run python -m ffmpeg_normalize [args]  # Test the tool directly

Code Quality

uv run ruff check .                # Linting
uv run ruff format .               # Auto-format code
uv run mypy src/ffmpeg_normalize   # Type checking

Documentation

pdoc -d google -o docs-api ./ffmpeg_normalize          # Generate API docs
uvx --with mkdocs-material mkdocs serve                # Preview docs locally
uvx --with mkdocs-material mkdocs gh-deploy            # Deploy docs

Getting Help

Check existing issues
Create a new issue for bugs or feature requests
Join discussions for questions and ideas

License

By contributing, you agree that your contributions will be licensed under the MIT License.