dialogue-guardian 1.2.0

Universal Media Censor - Automatically detect and censor profane language in video files

Dialogue Guardian: Universal Media Censor

This project provides two Python scripts to automatically detect and censor profane language in video files by processing SRT subtitle files.

• guardian_by_ffmpeg.py (Recommended): A standalone, cross-platform tool that directly censors audio using FFmpeg.
• guardian.py (Legacy): A tool that generates a Final Cut Pro XML (.fcpxml) file with volume keyframes to mute profane segments.

---

Installation

From PyPI (when published)

pip install dialogue-guardian

From Source

git clone <repository-url>
cd dialogue-guardian
pip install -e .

Development Installation

git clone <repository-url>
cd dialogue-guardian
make install-dev

Usage

Command Line Interface

After installation, you can use the guardian command:

# Basic usage
guardian movie.mp4

# With custom output path
guardian movie.mp4 --output censored_movie.mp4

# With verbose logging
guardian movie.mp4 --verbose

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

Python API

from guardian import GuardianProcessor

# Initialize the processor
processor = GuardianProcessor()

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

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

# Custom configuration
processor = GuardianProcessor(
    matching_words=['custom', 'word', 'list'],
    ffmpeg_cmd='/usr/local/bin/ffmpeg',
    ffprobe_cmd='/usr/local/bin/ffprobe'
)

Key Features

• Direct Audio Censoring: Uses FFmpeg's audio filters to mute profane segments and create a new, censored video file.
• Universal Compatibility: Works on any OS with FFmpeg installed (Windows, macOS, Linux).
• No FCPX Dependency: Does not require Final Cut Pro.
• 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.
• Efficient: Copies the video stream without re-encoding to maintain quality, only re-encoding the audio.
• Package Structure: Properly structured as a Python package for easy installation and distribution.

Requirements

• Python 3.7+
• FFmpeg: Installed and accessible in your system's PATH.
• Python Packages: Automatically installed with the package

---

guardian.py (Legacy FCPXML Workflow)

This script is for users who want to import a censorship timeline into Apple's Final Cut Pro.

Features

• FCPXML Generation: Outputs a ready-to-import XML file for Final Cut Pro with volume keyframes to mute profanity.
• Metadata Extraction: Uses ffprobe to get video details for the FCPXML project.
• Subtitle Parsing: Reads an external .srt file to find profane words.

Requirements

• Python 3.7+
• ffprobe (part of FFmpeg): The script defaults to /Users/Shared/FFmpegTools/ffprobe, but you can edit the path in the script.

Usage

1. Prepare your files:

   • Place your video file (e.g., movie.mp4) and its subtitle file (movie.srt) in the same directory.

2. Run the script:

   python guardian.py <path_to_your_video_file>
   

   Example:

   python guardian.py movie.mp4
   

3. Output:

   • A Final Cut Pro XML file (movie.fcpxml) will be generated.
   • A log file (guardian.log) will be created.

---

Customization

To customize the list of censored words, edit the matching_words list at the top of either guardian.py or guardian_by_ffmpeg.py.

---

Development

Running Tests

# Run all tests
make test

# Run tests with verbose output
make test-verbose

# Run specific test file
pytest tests/test_guardian_core.py

Code Quality

# Format code
make format

# Run linting
make lint

# Run all checks
make check

Building and Publishing

# Build the package
make build

# Upload to PyPI (requires credentials)
make upload

Testing

This project includes a full suite of unit tests. For detailed instructions on how to run the tests, please see TESTING.md.

---

License

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

---

Author

Created by Tony Snearly.