Dialogue Guardian

Universal Media Censor - Automatically detect and censor profane language in video files using subtitle analysis and FFmpeg audio processing.

🚀 Quick Start

# Install from PyPI
pip install dialogue-guardian

# Censor a video file
guardian --input movie.mp4

# Output: movie_censored.mp4

✨ Features

• 🎯 Direct Audio Censoring: Uses FFmpeg to mute profane segments in video files
• 🌍 Universal Compatibility: Works on any OS with FFmpeg installed (Windows, macOS, Linux)
• 🔄 Automatic SRT Extraction: If an external SRT file isn't found, it automatically extracts embedded SRT tracks from the video
• 🛡️ Non-Destructive: Creates a new video file, leaving the original untouched
• 📦 Package Structure: Properly structured as a Python package for easy installation and distribution
• 🎬 FCPX Support: Legacy support available for Final Cut Pro XML generation, but does not require Final Cut Pro
• 📹 Efficient Processing: Copies video streams without re-encoding to maintain quality
• 🎛 Enhanced Audio Censoring: Advanced multi-strategy audio filtering system with progressive fallback mechanisms
• 📡 Silence Verification: Automated verification that censored segments achieve target silence levels (≤ -50 dB)
• 🎚 Fallback Strategies: Three-tier approach (Basic → Enhanced → Aggressive) ensures effective censoring
• 🎙 Quality Preservation: Maintains video quality while achieving effective audio silence
• 🧰 Comprehensive Diagnostics: Detailed logging and JSON diagnostic reports for troubleshooting
• 🏷 Robust Error Handling: Graceful handling of missing files, corrupted data, and processing failures
• 🧪 High-Quality Testing: 86% test coverage with pure function testing (no mocks) for reliable logic validation
• 🔧 Modular Architecture: Refactored codebase with extracted pure functions for better maintainability and testability

📋 Requirements

• Python 3.7+
• FFmpeg (must be installed and accessible in PATH)

🛠️ Installation

From PyPI (Recommended)

pip install dialogue-guardian

From Source

git clone https://github.com/tsnearly/dialogue-guardian.git
cd dialogue-guardian
pip install -e .   or   uv sync

Development Installation

git clone https://github.com/tsnearly/dialogue-guardian.git
cd dialogue-guardian
make install-dev   or   uv sync --group dev

💻 Usage

Command Line Interface

# Basic usage
guardian --input movie.mp4

# Custom output path
guardian --input movie.mp4 --output censored_movie.mp4

# Verbose logging
guardian --input movie.mp4 --verbose

# Custom FFmpeg paths
guardian --input movie.mp4 --ffmpeg-path /usr/local/bin/ffmpeg

Python API

from guardian import GuardianProcessor

# Initialize processor
processor = GuardianProcessor()

# Process video
censored_file = processor.process_video("movie.mp4")

if censored_file:
    print(f"Censored video created: {censored_file}")

🧪 Testing

The project features comprehensive testing with 86% code coverage and a focus on testing real logic rather than mocked interfaces.

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test
pytest tests/test_guardian_core.py -v

# Run pure function tests (no mocks)
pytest tests/test_guardian_pure_functions.py -v

📈 Test Architecture

• 115 total tests across 7 test files
• 34 pure function tests that test actual logic without mocks
• Real data testing for parsing, filtering, and processing logic
• Edge case coverage including malformed data, division by zero, and encoding issues
• Integration tests with sample media files for end-to-end validation

📊 Current Code Coverage: 86%

🏗️ Development

Setup Development Environment

# Clone and setup
git clone https://github.com/tsnearly/dialogue-guardian.git
cd dialogue-guardian
make install-dev

# Run quality checks
make lint
make format
make check

Building and Publishing

# Build package
make build

# Upload to PyPI
make upload

Releases

📚 Documentation

• 📖 Full Documentation - Complete documentation on GitHub Pages
• Development Guide
• Testing Documentation
• Migration Summary
• Project Completion Summary

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Open Software License version 3.0 - see the LICENSE file for details.

👨‍💻 Author

Tony Snearly

🙏 Acknowledgments

• FFmpeg team for the powerful multimedia framework
• Python community for excellent tooling and libraries

---

⭐ Star this repository if you find it helpful!