Metadata-Version: 2.4
Name: dialogue-guardian
Version: 1.2.0
Summary: Universal Media Censor - Automatically detect and censor profane language in video files
Home-page: https://github.com/tsnearly/dialogue-guardian
Author: Tony Snearly
License: OSL-3.0
Project-URL: Homepage, https://github.com/tsnearly/dialogue-guardian
Project-URL: Documentation, https://tsnearly.github.io/dialogue-guardian/
Project-URL: Repository, https://github.com/tsnearly/dialogue-guardian.git
Project-URL: Issues, https://github.com/tsnearly/dialogue-guardian/issues
Project-URL: Changelog, https://tsnearly.github.io/dialogue-guardian/changelog.html
Keywords: video,audio,censoring,subtitles,ffmpeg,profanity,media
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Filters
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: srt
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<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 licensed under the Open Software License version 3.0 - see the [LICENSE](LICENSE) file for details.

---

## Author

Created by Tony Snearly.
