Stream Recorder

A high-performance CLI tool written in Rust for recording live streams from a variety of platforms. It automatically monitors specified accounts or channels, records streams with FFmpeg, generates thumbnails, uploads content to multiple file hosting services, and sends notifications via Discord webhooks.

Features

• Stream Monitoring: Continuously monitor multiple accounts across supported platforms for live streams
• Automatic Recording: Record streams using FFmpeg with optimized settings for quality and performance
• Thumbnail Generation: Automatically create video thumbnail grids for recorded streams
• Multi-Platform Uploads: Upload recordings and thumbnails to Bunkr, GoFile, and JPG6
• Discord Integration: Send real-time notifications for recording start/completion via Discord webhooks
• Disk Space Management: Automatically clean up old recordings when disk space is low
• Template System: Customizable notification messages with template variables

Prerequisites

• Rust
• FFmpeg (must be installed and available in PATH)

Usage

To begin recording streams, you need to either install or create a platform json file. If you are looking to create your own, look into /platforms/* for examples.

To install an already existing one, you can use the cli.

stream-recorder platform install {url}

Installation

From Source

git clone https://github.com/sn0w12/stream-recorder-rs.git

cd stream-recorder-rs

cargo build --release

The binary will be available at target/release/stream-recorder.exe (Windows) or target/release/stream-recorder (Linux/macOS).

Quick Start

For additional help, run:

stream-recorder -h

1. Save a platform API token (if required by the platform):

   Using keyring (recommended):

   stream-recorder token save-platform PLATFORM_ID YOUR_TOKEN_HERE
   
   

   Or define tokens in a .env file at ~/.config/stream-recorder/.env:

   PLATFORM_API_TOKEN=YOUR_TOKEN_HERE
   

2. Configure monitored accounts (use platform_id:username format):

   stream-recorder config add monitors platform1:user1
   
   stream-recorder config add monitors platform2:user2
   
   

3. Set output directory (optional):

   stream-recorder config set output_directory ./my_recordings
   
   

4. Start monitoring:

   stream-recorder --token YOUR_TOKEN
   
   

   Or if tokens are saved:

   stream-recorder
   
   

The tool will run continuously, monitoring for live streams and recording them automatically.

Stream Recording Flow

The diagram below shows the main phases of a recording session and how the major parts of the system interact.

flowchart TD
    A[Start application] --> B[Load config and platform definitions]
    B --> C[Create monitor tasks for configured accounts]
    C --> D[Poll platform pipelines for live status]

    D --> E{Stream live?}
    E -->|No| F[Wait and poll again]
    F --> D

    E -->|Yes| G[Start recording with FFmpeg]
    G --> H[Save stream segment to disk]
    H --> I{Continuation window enabled?}

    I -->|No| J[Post-process recording]
    I -->|Yes| K[Wait for stream continuation]
    K --> L{Stream resumes?}
    L -->|Yes| G
    L -->|No| M[Merge session segments]
    M --> J

    J --> N[Check retention and minimum duration rules]
    N --> O[Generate thumbnail and metadata]
    O --> P[Upload to enabled services]
    P --> Q[Render notification template]
    Q --> R[Send Discord notifications]
    R --> S[Recording session complete]
    S --> D

    style A fill:#d9f2ff,stroke:#1f6f8b,color:#111
    style D fill:#fff4d6,stroke:#a36a00,color:#111
    style G fill:#e8f7e8,stroke:#2f7d32,color:#111
    style J fill:#ffe6e6,stroke:#b42318,color:#111

Configuration

Configuration is stored in ~/.config/stream-recorder/config.toml (Linux/macOS) or %APPDATA%\stream-recorder\config.toml (Windows).

Available Settings

Setting	Description	Default
output_directory	Directory to save recordings	./recordings
monitors	List of usernames to monitor	None
discord_webhook_url	Discord webhook URL for notifications	None
min_free_space_gb	Minimum free disk space before cleanup	20.0
upload_complete_message_template	Template for upload completion messages	None
max_upload_retries	Maximum number of upload retries	3
min_stream_duration	Minimum stream duration before recording	None
bitrate	Bitrate to record stream at	3M
stream_reconnect_delay_minutes	Delay in minutes to wait for stream continuation before post-processing. Streams resumed are merged.	None
disabled_uploaders	List of uploaders to skip uploading to	None
step_delay_seconds	Delay in seconds between each step in a platform	0.5
fetch_interval_seconds	The interval in seconds monitors are fetched at	120.0

Configuration Commands

# View all configuration

stream-recorder config get


# Get specific setting

stream-recorder config get output_directory


# Set a configuration value

stream-recorder config set output_directory /path/to/recordings


# Get config file path

stream-recorder config get-path


# Manage monitored users

stream-recorder config monitors add username

stream-recorder config monitors remove username

stream-recorder config monitors list

Token Management

Tokens can be stored in two ways:

Option 1: System Keyring (Recommended)

Store tokens securely using the system keyring:

# Bunkr upload token

stream-recorder token save-bunkr YOUR_BUNKR_TOKEN


# GoFile upload token

stream-recorder token save-gofile YOUR_GOFILE_TOKEN

Option 2: .env File

Alternatively, you can store tokens in a .env file located at ~/.config/stream-recorder/.env (Linux/macOS) or %APPDATA%\stream-recorder\.env (Windows).

Create the file with the following format:

BUNKR_TOKEN=your_bunkr_token_here
GOFILE_TOKEN=your_gofile_token_here

Note: If both keyring and .env file contain tokens, the keyring tokens will take precedence.

Discord Integration

Set up Discord notifications:

1. Create a webhook in your Discord server
2. Set the webhook URL:

   stream-recorder config set discord_webhook_url https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
   
   

The tool will send notifications when:

• Recording starts
• Recording completes
• Uploads complete

Template System

Templates are rendered using Handlebars, a powerful templating engine. You can use all standard Handlebars features: variables, conditionals, loops, and block helpers. See the Handlebars documentation for syntax and advanced usage.

Built-in Helpers

The following helpers are registered and available in all templates:

Helper	Description
add	Adds two numbers. Usage: {{add a b}}
gt	Returns true if first number is greater than second. Usage: {{#if (gt a b)}}...{{/if}}
ne	Returns true if two values are not equal. Usage: {{#if (ne a b)}}...{{/if}}

For real-world usage, see the example template: templates/example.hbr

Template Variables

The following variables are available in the template context:

Variable	Type	Description
date	String	Current date (YYYY-MM-DD)
username	String	Streamer's username
user_id	String	Streamer's user ID
output_path	String	Path to recorded video file
thumbnail_path	String	Path to generated thumbnail
stream_title	String	Title of the stream
<uploader>_urls	Array	Array of an uploaders uploaded URLs
<uploader>_urls_len	Number	Length of any array variable (e.g. bunkr_urls_len)

Testing Templates

Render a test message with mock data:

stream-recorder template render

Upload Services

The tool supports uploading to multiple services. Tokens are stored securely and used automatically when available.

Bunkr

• Requires API token
• Uploads video files

GoFile

• Requires API token
• Uploads video files

File Organization

Recordings are organized as follows:

output_directory/
├── username1/
│   ├── username1_2025-01-01_12-00-00.mp4
│   ├── username1_2025-01-01_12-00-00_thumb.jpg
│   └── ...
└── username2/
    └── ...

Disk Space Management

The tool automatically manages disk space by:

• Monitoring free space in the output directory
• Deleting oldest recordings when space falls below min_free_space_gb
• Removing associated thumbnail files

License

This project is licensed under the MIT License - see the LICENSE file for details.