# 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.
```bash
stream-recorder platform install {url}
```
## Installation
### From Source
```bash
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:
```bash
stream-recorder -h
```
1. **Save a platform API token** (if required by the platform):
Using keyring (recommended):
```bash
stream-recorder token save-platform PLATFORM_ID YOUR_TOKEN_HERE
```
Or define tokens in a `.env` file at `~/.config/stream-recorder/.env`:
```env
PLATFORM_API_TOKEN=YOUR_TOKEN_HERE
```
2. **Configure monitored accounts** (use `platform_id:username` format):
```bash
stream-recorder config add monitors platform1:user1
stream-recorder config add monitors platform2:user2
```
3. **Set output directory (optional):**
```bash
stream-recorder config set output_directory ./my_recordings
```
4. **Start monitoring:**
```bash
stream-recorder --token YOUR_TOKEN
```
Or if tokens are saved:
```bash
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.
```mermaid
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
| `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
```bash
# 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:
```bash
# 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:
```env
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:
```bash
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](https://handlebarsjs.com/), a powerful templating engine. You can use all standard Handlebars features: variables, conditionals, loops, and block helpers. See the [Handlebars documentation](https://handlebarsjs.com/guide/) for syntax and advanced usage.
### Built-in Helpers
The following helpers are registered and available in all templates:
| `add` | Adds two numbers. <br>Usage: `{{add a b}}` |
| `gt` | Returns true if first number is greater than second. <br>Usage: `{{#if (gt a b)}}...{{/if}}` |
| `ne` | Returns true if two values are not equal. <br>Usage: `{{#if (ne a b)}}...{{/if}}` |
For real-world usage, see the example template: [templates/example.hbr](templates/example.hbr)
### Template Variables
The following variables are available in the template context:
| `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:
```bash
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.