From 77d9bd5e10ca90f93e223aa8c0a6d58a0a23f488 Mon Sep 17 00:00:00 2001 From: Benjamin Slingo Date: Mon, 8 Sep 2025 12:58:34 -0400 Subject: [PATCH] Update README.md --- README.md | 184 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 144 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index a3da792..c5fcb9f 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,29 @@ # Sermon Converter -A Rust-based service that automatically monitors a directory for new sermon video files and converts them to an optimized format for streaming. +An event-driven Rust service that automatically detects and converts sermon video files for efficient storage and streaming. Uses the shared `video_processing` crate for optimal performance. ## Features -- Automatic detection of new MP4 files in the watch directory -- Efficient video conversion using FFmpeg -- Preserves audio quality while optimizing video for streaming -- Automatic file organization with date-based naming -- Syncthing-aware (ignores temporary sync files) +- **Event-driven file detection** - No polling, instant response to new files +- **AV1 video conversion** with Intel QSV hardware acceleration +- **Preserves original filenames** - Backend handles metadata parsing +- **File stability checking** - Ensures files are fully written before processing +- **Syncthing-aware** - Ignores temporary sync files +- **Efficient disk space usage** with modern compression +- **Configurable via environment variables** ## Prerequisites - Rust (latest stable version) -- FFmpeg installed and available in PATH +- FFmpeg with AV1 support (or configure different codec) +- Intel Media SDK (for QSV acceleration, optional) - Sufficient disk space for video processing ## Installation 1. Clone the repository: ```bash -git clone +git clone cd sermon-converter ``` @@ -31,15 +34,40 @@ cargo build --release ## Configuration -The service uses environment variables for configuration: +Create a `.env` file based on `.env.example`: -- `SERMON_WATCH_PATH`: Directory to monitor for new sermon videos -- `SERMON_OUTPUT_PATH`: Directory where converted videos will be saved - -Example: ```bash -export SERMON_WATCH_PATH="/path/to/watch/directory" -export SERMON_OUTPUT_PATH="/path/to/output/directory" +cp .env.example .env +nano .env +``` + +### Required Environment Variables + +```bash +# Directory paths (REQUIRED) +SERMON_WATCH_PATH=/path/to/watch/sermons +SERMON_OUTPUT_PATH=/path/to/output/sermons + +# FFmpeg Configuration +FFMPEG_BINARY=ffmpeg +VIDEO_CODEC=av1_qsv # or libx264, libx265, etc. +HW_ACCEL=qsv # hardware acceleration +HW_DEVICE=qsv=hw +FFMPEG_PRESET=4 +VIDEO_BITRATE=6M +MAX_BITRATE=12M +BUFFER_SIZE=24M +AUDIO_CODEC=libopus # or copy, aac, etc. +AUDIO_BITRATE=192k + +# File Stability Settings +STABILITY_CHECK_INTERVAL=1 # seconds between stability checks +STABILITY_REQUIRED_CHECKS=30 # consecutive stable checks required +MAX_STABILITY_WAIT_HOURS=0.5 # maximum time to wait for stability + +# Directory Settings +CREATE_YEAR_MONTH_DIRS=true # organize by date (unused currently) +PRESERVE_ORIGINAL_FILES=false # delete original after conversion ``` ## Usage @@ -56,12 +84,27 @@ Or run the built binary: The service will: 1. Process any existing MP4 files in the watch directory -2. Continue monitoring for new files -3. Automatically convert new MP4 files as they appear +2. Watch for new files using efficient event-driven detection +3. Wait for file stability before processing +4. Convert to optimized format with same filename +5. Output converted files for backend metadata handling + +## Expected File Format + +Sermon files should follow the naming convention: +``` +Title - Speaker Month Day Year.mp4 +``` + +Examples: +- `God's People in the Time of the End - Pastor John Smith December 28 2024.mp4` +- `The Great Hope - Elder Jane Doe January 15 2025.mp4` + +The backend will parse this format automatically for metadata. ## Running as a System Service -To run as a systemd service, create a service file at `/etc/systemd/system/sermon-converter.service`: +Create a systemd service file at `/etc/systemd/system/sermon-converter.service`: ```ini [Unit] @@ -70,10 +113,23 @@ After=network.target [Service] Type=simple -User= -Environment="SERMON_WATCH_PATH=/path/to/watch/directory" -Environment="SERMON_OUTPUT_PATH=/path/to/output/directory" -ExecStart=/path/to/sermon_converter +User=rockvilleav +Group=rockvilleav +ExecStart=/usr/local/bin/sermon_converter +WorkingDirectory=/home/rockvilleav/sermon-converter + +# Load environment variables from .env file +EnvironmentFile=/home/rockvilleav/sermon-converter/.env + +# System environment variables +Environment=HOME=/home/rockvilleav +Environment=USER=rockvilleav + +# Intel Media Stack (if using QSV) +Environment=LIBVA_DRIVER_NAME=iHD +Environment=LIBVA_DRIVERS_PATH=/opt/intel/media/lib64 +Environment=LD_LIBRARY_PATH=/opt/intel/media/lib64 + Restart=always RestartSec=10 @@ -85,30 +141,78 @@ Enable and start the service: ```bash sudo systemctl enable sermon-converter sudo systemctl start sermon-converter +sudo systemctl status sermon-converter ``` +View logs: +```bash +sudo journalctl -u sermon-converter -f +``` + +## Architecture + +This service uses a clean, event-driven architecture: + +- **Event Detection**: Uses `inotify` for instant file detection (no polling) +- **File Stability**: Ensures files are completely written before processing +- **Shared Logic**: Uses `video_processing` crate for common functionality +- **Simple Processing**: Convert file, keep same name, let backend handle metadata +- **Resource Efficient**: Only uses CPU/disk when actually processing files + ## Video Conversion Details -The service converts videos using the following FFmpeg settings: -- Video codec: H.264 (libx264) -- Audio codec: AAC -- Video preset: medium -- Constant Rate Factor (CRF): 23 -- Pixel format: yuv420p -- Audio bitrate: 128k -- Audio sample rate: 44100 Hz - -## File Naming Convention - -Converted files are named based on the original filename's date pattern: -- Input: `YYYY-MM-DD_sermon.mp4` -- Output: `YYYY-MM-DD_sermon_converted.mp4` +Default settings (configurable via .env): +- **Video Codec**: AV1 with Intel QSV acceleration +- **Audio Codec**: Opus (high efficiency) +- **Hardware Acceleration**: Intel Quick Sync Video +- **Video Bitrate**: 6Mbps (configurable) +- **Audio Bitrate**: 192kbps (configurable) ## Troubleshooting -- **FFmpeg not found**: Ensure FFmpeg is installed and in your system PATH -- **Permission denied**: Check that the service has read/write permissions for both watch and output directories -- **Files not detected**: Verify the watch directory path and that files are complete before processing +### Common Issues + +**Service fails to start:** +```bash +# Check if .env file exists and has correct paths +ls -la /home/rockvilleav/sermon-converter/.env + +# Verify directories exist and are accessible +ls -la /path/to/watch/sermons +ls -la /path/to/output/sermons +``` + +**FFmpeg errors:** +```bash +# Test FFmpeg with your codec +ffmpeg -encoders | grep av1 +ffmpeg -hwaccels | grep qsv + +# Check Intel Media SDK installation +vainfo +``` + +**Files not being detected:** +```bash +# Check logs for file events +sudo journalctl -u sermon-converter -f + +# Verify file permissions +ls -la /path/to/watch/sermons/ +``` + +**Out of disk space:** +```bash +# Service checks for 5GB minimum free space +df -h /path/to/output/sermons +``` + +### Log Analysis + +The service provides detailed logging: +- `INFO` level: Normal operation, file detection, conversion progress +- `WARN` level: Non-fatal issues (low disk space, sync failures) +- `ERROR` level: Conversion failures, configuration errors ## License @@ -116,4 +220,4 @@ See LICENSE file for details. ## Contributing -Contributions are welcome! Please submit pull requests or issues through the repository. \ No newline at end of file +Contributions are welcome! This service is part of a larger church media processing system. \ No newline at end of file