stream-sprout/AGENTS.md

AGENTS.md

Overview

Stream Sprout is a bash-based RTMP restreaming tool that forwards a single video source (from OBS Studio or similar) to multiple destinations like Twitch, YouTube, Owncast, and Peertube simultaneously. It uses FFmpeg's tee muxer to copy streams without transcoding.

Tech Stack

• Language: Bash 5.0+ (single script: stream-sprout)
• Runtime dependency: FFmpeg (RTMP server and restreaming)
• Configuration: YAML parsed via awk/sed
• Packaging: Nix flake, Debian .deb, Snap, Docker/Podman

Build and Run Commands

# Run directly (requires ffmpeg, bash 5.0+, awk, grep, sed)
./stream-sprout --config stream-sprout.yaml

# Show version and FFmpeg info
./stream-sprout --version

# Show system info (useful for bug reports)
./stream-sprout --info

# Nix build
nix build

# Enter development shell with all dependencies
nix develop

# Docker build and run
docker build -t stream-sprout .
docker run -p 1935:1935 -it -v $PWD:/data stream-sprout --config /data/stream-sprout.yaml

Linting

ShellCheck is enforced via CI on all pull requests.

# Run locally before committing
shellcheck stream-sprout

The script includes # shellcheck disable=SC2154 for variables set dynamically via eval from YAML parsing.

Code Style

• Bash scripts use #!/usr/bin/env bash
• Functions use function name() {} syntax
• Use local for function-scoped variables
• Use readonly for constants
• Validation with informative error messages using Unicode icons and ANSI colours
• Version is tracked in the script: readonly VERSION="x.y.z"

Project Structure

stream-sprout           # Main bash script (single file)
stream-sprout.yaml      # Local config (gitignored)
stream-sprout.yaml.example  # Example configuration
package.nix             # Nix package definition
devshell.nix            # Nix development shell
flake.nix               # Nix flake
Dockerfile              # Alpine-based container

Configuration

YAML config with two main sections:

• server: - RTMP server settings (ip, port, app, key, archive options)
• services: - Destination services (each with enabled, rtmp_server, key)

Config search order: ./stream-sprout.yaml, $XDG_CONFIG_HOME/stream-sprout.yaml, /etc/stream-sprout.yaml

PR and Commit Guidelines

• Commit messages must follow Conventional Commits
• PR titles are validated against Conventional Commits format
• Single-commit PRs must have matching PR title and commit message
• ShellCheck must pass with no warnings

Common prefixes: feat:, fix:, chore:, refactor:, docs:

Version Updates

When changing version:

1. Update VERSION in stream-sprout script
2. The Nix package extracts version automatically from the script

Constraints

• Requires bash 5.0 or newer
• FFmpeg must be available on PATH
• RTMP only (no RTMPS support currently)
• FFmpeg does not enforce stream keys (documented security limitation)

Security Considerations

• Stream keys are stored in plain text in YAML config
• FFmpeg accepts any RTMP stream on the configured port regardless of app/key path
• Do not expose the RTMP port to untrusted networks without additional protection (VPN, firewall, SSH tunnel)