From 6bf2eb38aae0b98166f31d3623a937bb0dabffc7 Mon Sep 17 00:00:00 2001 From: RTSDA Date: Sat, 16 Aug 2025 19:05:59 -0400 Subject: [PATCH] Add documentation and configuration templates - Add comprehensive .gitignore for Rust projects - Add MIT LICENSE file - Add detailed README with installation and usage instructions - Add generic service file template (livestream-archiver.service.example) - Add generic deployment script template (deploy.sh.example) - Keep sensitive configuration out of version control --- .gitignore | 40 +++++++ LICENSE | 21 ++++ README.md | 166 ++++++++++++++++++++++++++++ deploy.sh.example | 87 +++++++++++++++ livestream-archiver.service.example | 16 +++ 5 files changed, 330 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100644 deploy.sh.example create mode 100644 livestream-archiver.service.example diff --git a/.gitignore b/.gitignore index 6990990..7ed3ce8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,42 @@ +# Rust build artifacts /target +/debug +/release + +# Test files *.mp4 +*.avi +*.mkv +*.mov +test.* +output.* + +# Package and deployment artifacts +/package/ +*.tar.gz +*.tar +*.zip +livestream-archiver-deploy.tar.gz + +# OS files +.DS_Store +Thumbs.db + +# Editor files +*.swp +*.swo +*~ +.vscode/ +.idea/ + +# Cache files +.cache/ + +# Local configuration files (contain sensitive data) +livestream-archiver.service +deploy.sh +DEPLOY.md + +# Keep example files +!*.example +!*.template \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..10e4095 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Livestream Archiver Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b263fbc --- /dev/null +++ b/README.md @@ -0,0 +1,166 @@ +# Livestream Archiver + +A Rust application that monitors a directory for livestream recordings, processes them with hardware-accelerated transcoding, and syncs them to a remote server. + +## Features + +- **Automatic Detection**: Monitors a configured directory for new MP4 files +- **Smart Processing**: Waits for files to be completely written before processing +- **Remote Sync**: Uses rsync to sync files to a remote server immediately after detection +- **Hardware Acceleration**: Converts files to AV1 using Intel QSV hardware acceleration +- **Organized Storage**: Creates date-based directory structure (Jellyfin-compatible) +- **Metadata Generation**: Creates NFO files for media servers +- **Retry Logic**: Caches and retries failed sync operations +- **Service Integration**: Runs as a systemd service with automatic restart + +## Prerequisites + +- Rust toolchain (1.70 or later) +- `ffmpeg` with Intel QSV support +- `rsync` for file synchronization +- SSH key authentication for passwordless rsync (if using remote sync) + +## Installation + +### Building from Source + +```bash +# Clone the repository +git clone +cd livestream-archiver + +# Build release binary +cargo build --release + +# Binary will be at target/release/livestream_archiver +``` + +### Quick Deploy + +1. Copy and customize the example files: +```bash +cp livestream-archiver.service.example livestream-archiver.service +cp deploy.sh.example deploy.sh +# Edit both files with your specific configuration +``` + +2. Run the deployment: +```bash +./deploy.sh +``` + +## Configuration + +### Environment Variables + +- `PC_SYNC_TARGET`: Remote sync destination (e.g., `user@server:/path/to/destination/`) +- `INPUT_DIR`: Directory to monitor for new files +- `OUTPUT_DIR`: Local output directory for processed files + +### Service Configuration + +1. Copy the example service file: +```bash +cp livestream-archiver.service.example livestream-archiver.service +``` + +2. Edit the service file with your configuration: +- Update `User` and `Group` +- Set correct paths for `WorkingDirectory` and `ExecStart` +- Configure the `PC_SYNC_TARGET` environment variable + +3. Install and start the service: +```bash +sudo cp livestream-archiver.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable livestream-archiver +sudo systemctl start livestream-archiver +``` + +## Usage + +### Running Manually + +```bash +# Run directly +cargo run + +# Or run the compiled binary +./target/release/livestream_archiver +``` + +### Running as a Service + +```bash +# Check service status +sudo systemctl status livestream-archiver + +# View logs +sudo journalctl -u livestream-archiver -f + +# Restart service +sudo systemctl restart livestream-archiver +``` + +## How It Works + +1. **Monitoring**: Continuously watches the input directory for new MP4 files +2. **Validation**: Waits for files to be completely written (stable size) +3. **Sync**: Immediately syncs new files to the remote server via rsync +4. **Processing**: Converts to AV1 format using hardware acceleration +5. **Organization**: Moves processed files to date-based directories +6. **Metadata**: Creates NFO files for media server compatibility +7. **Cleanup**: Optionally removes original files after successful processing + +## Directory Structure + +Output files are organized by date: +``` +/ +├── 2024/ +│ ├── 01-January/ +│ │ ├── Recording - January 01 2024.mp4 +│ │ ├── Recording - January 01 2024.nfo +│ │ └── ... +│ └── 02-February/ +│ └── ... +└── 2025/ + └── ... +``` + +## Troubleshooting + +### Service not starting +- Check logs: `journalctl -u livestream-archiver -f` +- Verify all paths exist and have proper permissions +- Ensure ffmpeg has QSV support: `ffmpeg -hwaccels | grep qsv` + +### Sync failures +- Verify SSH key authentication to remote server +- Check network connectivity +- Review cached sync attempts in `~/.cache/livestream-archiver/` + +### Processing issues +- Ensure Intel QSV drivers are installed +- Check available disk space +- Verify file permissions in input/output directories + +## Development + +### Running Tests +```bash +cargo test +``` + +### Building for Debug +```bash +cargo build +``` + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. \ No newline at end of file diff --git a/deploy.sh.example b/deploy.sh.example new file mode 100644 index 0000000..c653272 --- /dev/null +++ b/deploy.sh.example @@ -0,0 +1,87 @@ +#!/bin/bash + +# Deployment script for Livestream Archiver +# Usage: Copy to deploy.sh and customize for your environment + +SERVER="user@your-server.com" +PORT="22" +REMOTE_PATH="/path/to/livestream-archiver" +SERVICE_NAME="livestream-archiver" + +echo "🚀 Starting deployment to $SERVER:$PORT" + +# Build release binary +echo "📦 Building release binary..." +cargo build --release + +if [ $? -ne 0 ]; then + echo "❌ Build failed!" + exit 1 +fi + +echo "✅ Build successful!" + +# Create deployment directory +echo "📁 Creating deployment directory..." +mkdir -p deploy + +# Copy necessary files to deploy directory +echo "📋 Copying files..." +cp target/release/livestream_archiver deploy/ +cp livestream-archiver.service deploy/ +cp README.md deploy/ + +# Create deployment package +echo "📦 Creating deployment package..." +tar -czf livestream-archiver-deploy.tar.gz -C deploy . + +# Copy to server +echo "🔄 Copying to server..." +scp -P $PORT livestream-archiver-deploy.tar.gz $SERVER:/tmp/ + +# Deploy on server +echo "🚀 Deploying on server..." +ssh -p $PORT $SERVER << 'EOF' + # Stop existing service if running + sudo systemctl stop livestream-archiver 2>/dev/null || true + + # Create application directory + sudo mkdir -p /path/to/livestream-archiver + + # Extract deployment package + cd /tmp + tar -xzf livestream-archiver-deploy.tar.gz -C /path/to/livestream-archiver/ + + # Set permissions + sudo chown -R service-user:service-group /path/to/livestream-archiver + sudo chmod +x /path/to/livestream-archiver/livestream_archiver + + # Install systemd service + sudo cp /path/to/livestream-archiver/livestream-archiver.service /etc/systemd/system/ + sudo systemctl daemon-reload + sudo systemctl enable livestream-archiver + + # Create required directories + sudo mkdir -p /path/to/input/directory + sudo mkdir -p /path/to/output/directory + sudo chown -R service-user:service-group /path/to/input/directory + + # Start service + sudo systemctl start livestream-archiver + + # Check status + echo "📊 Service status:" + sudo systemctl status livestream-archiver --no-pager + + # Clean up + rm -f /tmp/livestream-archiver-deploy.tar.gz +EOF + +echo "✅ Deployment complete!" +echo "📊 To check logs: ssh -p $PORT $SERVER 'sudo journalctl -u livestream-archiver -f'" +echo "🔄 To restart: ssh -p $PORT $SERVER 'sudo systemctl restart livestream-archiver'" + +# Clean up local files +rm -rf deploy livestream-archiver-deploy.tar.gz + +echo "🎉 All done!" \ No newline at end of file diff --git a/livestream-archiver.service.example b/livestream-archiver.service.example new file mode 100644 index 0000000..2f46cc2 --- /dev/null +++ b/livestream-archiver.service.example @@ -0,0 +1,16 @@ +[Unit] +Description=Livestream Archiver Service +After=network.target + +[Service] +Type=simple +User= +Group= +WorkingDirectory=/path/to/livestream-archiver +ExecStart=/path/to/livestream-archiver/target/release/livestream_archiver +Environment=PC_SYNC_TARGET=user@server:/path/to/destination/ +Restart=always +RestartSec=10 + +[Install] +WantedBy=multi-user.target \ No newline at end of file