<p align="center"><img src="logo.png" alt="Dialogue Guardian Logo" width="200"></p>
# 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)
```sh
pip install dialogue-guardian
```
### From Source
```sh
git clone <repository-url>
cd dialogue-guardian
pip install -e .
```
### Development Installation
```sh
git clone <repository-url>
cd dialogue-guardian
make install-dev
```
## Usage
### Command Line Interface
After installation, you can use the `guardian` command:
```sh
# 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
```python
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:**
```sh
python guardian.py <path_to_your_video_file>
```
Example:
```sh
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
```sh
# 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
```sh
# Format code
make format
# Run linting
make lint
# Run all checks
make check
```
### Building and Publishing
```sh
# 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](TESTING.md).
---
## License
This project is provided as-is, without warranty. You may modify and distribute as needed.
---
## Author
Created by Tony Snearly.
Raw data
{
"_id": null,
"home_page": "https://github.com/tsnearly/dialogue-guardian",
"name": "dialogue-guardian",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "video, audio, censoring, subtitles, ffmpeg, profanity, media",
"author": "Tony Snearly",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b7/4c/a5aaf20dd7571df0a167d4deb3760946ddd789c2785ea54365def97b411a/dialogue_guardian-1.1.2.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img src=\"logo.png\" alt=\"Dialogue Guardian Logo\" width=\"200\"></p>\n\n# Dialogue Guardian: Universal Media Censor\n\nThis project provides two Python scripts to automatically detect and censor profane language in video files by processing SRT subtitle files.\n\n- **`guardian_by_ffmpeg.py` (Recommended)**: A standalone, cross-platform tool that directly censors audio using FFmpeg.\n- **`guardian.py` (Legacy)**: A tool that generates a Final Cut Pro XML (`.fcpxml`) file with volume keyframes to mute profane segments.\n\n---\n\n## Installation\n\n### From PyPI (when published)\n```sh\npip install dialogue-guardian\n```\n\n### From Source\n```sh\ngit clone <repository-url>\ncd dialogue-guardian\npip install -e .\n```\n\n### Development Installation\n```sh\ngit clone <repository-url>\ncd dialogue-guardian\nmake install-dev\n```\n\n## Usage\n\n### Command Line Interface\n\nAfter installation, you can use the `guardian` command:\n\n```sh\n# Basic usage\nguardian movie.mp4\n\n# With custom output path\nguardian movie.mp4 --output censored_movie.mp4\n\n# With verbose logging\nguardian movie.mp4 --verbose\n\n# Custom FFmpeg paths\nguardian movie.mp4 --ffmpeg-path /usr/local/bin/ffmpeg --ffprobe-path /usr/local/bin/ffprobe\n```\n\n### Python API\n\n```python\nfrom guardian import GuardianProcessor\n\n# Initialize the processor\nprocessor = GuardianProcessor()\n\n# Process a video file\ncensored_file = processor.process_video(\"movie.mp4\")\n\nif censored_file:\n print(f\"Censored video created: {censored_file}\")\nelse:\n print(\"Processing failed\")\n\n# Custom configuration\nprocessor = GuardianProcessor(\n matching_words=['custom', 'word', 'list'],\n ffmpeg_cmd='/usr/local/bin/ffmpeg',\n ffprobe_cmd='/usr/local/bin/ffprobe'\n)\n```\n\n### Key Features\n\n- **Direct Audio Censoring**: Uses FFmpeg's audio filters to mute profane segments and create a new, censored video file.\n- **Universal Compatibility**: Works on any OS with FFmpeg installed (Windows, macOS, Linux).\n- **No FCPX Dependency**: Does not require Final Cut Pro.\n- **Automatic SRT Extraction**: If an external SRT file isn't found, it automatically extracts embedded SRT tracks from the video.\n- **Non-Destructive**: Creates a new video file, leaving the original untouched.\n- **Efficient**: Copies the video stream without re-encoding to maintain quality, only re-encoding the audio.\n- **Package Structure**: Properly structured as a Python package for easy installation and distribution.\n\n### Requirements\n\n- **Python 3.7+**\n- **FFmpeg**: Installed and accessible in your system's PATH.\n- **Python Packages**: Automatically installed with the package\n\n---\n\n## `guardian.py` (Legacy FCPXML Workflow)\n\nThis script is for users who want to import a censorship timeline into Apple's Final Cut Pro.\n\n### Features\n\n- **FCPXML Generation**: Outputs a ready-to-import XML file for Final Cut Pro with volume keyframes to mute profanity.\n- **Metadata Extraction**: Uses `ffprobe` to get video details for the FCPXML project.\n- **Subtitle Parsing**: Reads an external `.srt` file to find profane words.\n\n### Requirements\n\n- **Python 3.7+**\n- **ffprobe** (part of FFmpeg): The script defaults to `/Users/Shared/FFmpegTools/ffprobe`, but you can edit the path in the script.\n\n### Usage\n\n1. **Prepare your files:**\n - Place your video file (e.g., `movie.mp4`) and its subtitle file (`movie.srt`) in the same directory.\n\n2. **Run the script:**\n ```sh\n python guardian.py <path_to_your_video_file>\n ```\n Example:\n ```sh\n python guardian.py movie.mp4\n ```\n\n3. **Output:**\n - A Final Cut Pro XML file (`movie.fcpxml`) will be generated.\n - A log file (`guardian.log`) will be created.\n\n---\n\n## Customization\n\nTo customize the list of censored words, edit the `matching_words` list at the top of either `guardian.py` or `guardian_by_ffmpeg.py`.\n\n---\n\n## Development\n\n### Running Tests\n\n```sh\n# Run all tests\nmake test\n\n# Run tests with verbose output\nmake test-verbose\n\n# Run specific test file\npytest tests/test_guardian_core.py\n```\n\n### Code Quality\n\n```sh\n# Format code\nmake format\n\n# Run linting\nmake lint\n\n# Run all checks\nmake check\n```\n\n### Building and Publishing\n\n```sh\n# Build the package\nmake build\n\n# Upload to PyPI (requires credentials)\nmake upload\n```\n\n## Testing\n\nThis project includes a full suite of unit tests. For detailed instructions on how to run the tests, please see [TESTING.md](TESTING.md).\n\n---\n\n## License\n\nThis project is provided as-is, without warranty. You may modify and distribute as needed.\n\n---\n\n## Author\n\nCreated by Tony Snearly.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Universal Media Censor - Automatically detect and censor profane language in video files",
"version": "1.1.2",
"project_urls": {
"Bug Reports": "https://github.com/tsnearly/dialogue-guardian/issues",
"Homepage": "https://github.com/tsnearly/dialogue-guardian",
"Source": "https://github.com/tsnearly/dialogue-guardian"
},
"split_keywords": [
"video",
" audio",
" censoring",
" subtitles",
" ffmpeg",
" profanity",
" media"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ba743d170d71af940ff029dd8bb68df87d5fcef70d8b556645f2302d5603c582",
"md5": "6a2493ac132cd691f7ff3332ed7eaee0",
"sha256": "b01e8f7108568efab3eec9f39a4c378c403c25018ecc301ab6368a5a899fb1cf"
},
"downloads": -1,
"filename": "dialogue_guardian-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a2493ac132cd691f7ff3332ed7eaee0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10947,
"upload_time": "2025-09-08T17:37:32",
"upload_time_iso_8601": "2025-09-08T17:37:32.182611Z",
"url": "https://files.pythonhosted.org/packages/ba/74/3d170d71af940ff029dd8bb68df87d5fcef70d8b556645f2302d5603c582/dialogue_guardian-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b74ca5aaf20dd7571df0a167d4deb3760946ddd789c2785ea54365def97b411a",
"md5": "50f67c24963e4cf52ca5e68313803c17",
"sha256": "24a716e2617b56779a41059a5dafbc7214f6c9a6e177e79bcea7240d0e6a75b3"
},
"downloads": -1,
"filename": "dialogue_guardian-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "50f67c24963e4cf52ca5e68313803c17",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 214036,
"upload_time": "2025-09-08T17:37:33",
"upload_time_iso_8601": "2025-09-08T17:37:33.535445Z",
"url": "https://files.pythonhosted.org/packages/b7/4c/a5aaf20dd7571df0a167d4deb3760946ddd789c2785ea54365def97b411a/dialogue_guardian-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 17:37:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsnearly",
"github_project": "dialogue-guardian",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dialogue-guardian"
}
JSON
