Universal Media Censor - Automatically detect and censor profane language in video files using subtitle analysis and FFmpeg audio processing.
# Install from PyPI
pip install dialogue-guardian
# Censor a video file
guardian --input movie.mp4
# Output: movie_censored.mp4- 🎯 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
- Python 3.7+
- FFmpeg (must be installed and accessible in PATH)
pip install dialogue-guardiangit clone https://github.com/tsnearly/dialogue-guardian.git
cd dialogue-guardian
pip install -e . or uv syncgit clone https://github.com/tsnearly/dialogue-guardian.git
cd dialogue-guardian
make install-dev or uv sync --group dev# 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
- `--full` : When set, run the full (and slower) verification path which performs per-segment audio analysis using FFmpeg astats, produces a comprehensive diagnostic report, and allows multiple fallback attempts to improve censoring. Default: disabled (fast path). Use `--full` when you want maximum assurance at the cost of slower runs.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}")# Run all tests
make test
# Run with coverage
make test-coverage
# Run specific test
pytest tests/test_guardian_core.py -v
# 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# Build package
make build
# Upload to PyPI
make upload
- 📖 Full Documentation - Complete documentation on GitHub Pages
- Development Guide
- Testing Documentation
- Migration Summary
- Project Completion Summary
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the Open Software License version 3.0 - see the LICENSE file for details.
Tony Snearly
- FFmpeg team for the powerful multimedia framework
- Python community for excellent tooling and libraries
⭐ Star this repository if you find it helpful!