LiveLink

📚 LiveLink - Streaming Manager

A high-performance, race-condition-free streaming manager for Twitch, YouTube, and Holodex.

🚀 Quick Start

Installation

git clone https://github.com/yourrepo/LiveLink
cd LiveLink/rust
cargo build --release

Configuration

Create config/ directory with JSON files:

mkdir -p config

Environment Variables (Optional)

# Override config file values
export HOLODEX_API_KEY="your-key"
export TWITCH_CLIENT_ID="your-id"
export TWITCH_CLIENT_SECRET="your-secret"
export YOUTUBE_API_KEY="your-key"
export LIVELINK_CONFIG="/custom/config/path"
export LOG_LEVEL="debug"
export PORT="3001"

Run

# Server mode
cargo run

# CLI mode
cargo run -- stream list
cargo run -- screen enable 1

📁 Configuration Files

All config files go in config/ directory.

1. `favorites.json` – Favorite Channels

Format A: Per-platform (recommended)

{
  "holodex": {
    "default": [
      { "id": "UC3n9mTfC7Ib1P8Z-MqP5M8w", "name": "Mori Calliope", "score": 100 },
      { "id": "UCf5mFVsGjJ5y2qW9T5s5j5A", "name": "Gawr Gura", "score": 95 }
    ]
  },
  "twitch": {
    "default": [
      { "id": "monstercat", "name": "Monstercat", "score": 80 },
      { "id": "sodapoppin", "name": "Sodapoppin", "score": 75 }
    ]
  },
  "youtube": {
    "default": [
      { "id": "UCXuqSBlHAE6Xw-yeJA0Tunw", "name": "Ludwig", "score": 90 }
    ]
  }
}

Format B: Simple array (same for all platforms)

[
  { "id": "monstercat", "name": "Monstercat", "score": 100 },
  { "id": "sodapoppin", "name": "Sodapoppin", "score": 90 }
]

Format C: URLs only (auto-scores based on order)

{
  "urls": "https://twitch.tv/monstercat https://twitch.tv/sodapoppin https://youtube.com/@ludwig"
}

Field	Type	Description
`id`	string	Channel ID or username
`name`	string	Display name
`score`	number	Higher = higher priority (default: position-based)

2. `streams.json` – Screen & Stream Sources

{
  "streams": [
    {
      "id": 1,
      "screen": 1,
      "enabled": true,
      "width": 1920,
      "height": 1080,
      "x": 0,
      "y": 0,
      "volume": 70,
      "quality": "best",
      "window_maximized": true,
      "primary": true,
      "sources": [
        {
          "type": "holodex",
          "subtype": "organization",
          "enabled": true,
          "priority": 10,
          "limit": 20,
          "name": "Hololive"
        },
        {
          "type": "twitch",
          "subtype": "favorites",
          "enabled": true,
          "priority": 20
        },
        {
          "type": "youtube",
          "subtype": "popular",
          "enabled": true,
          "priority": 30,
          "limit": 10
        }
      ],
      "sorting": {
        "field": "viewerCount",
        "order": "desc",
        "ignore": ["members_only"]
      },
      "refresh": 60,
      "auto_start": true,
      "skip_watched_streams": true
    }
  ],
  "organizations": ["Hololive", "Nijisanji", "VShojo"]
}

ScreenConfig Fields

Field	Type	Default	Description
`id`	number	required	Unique screen ID
`screen`	number	required	Display/monitor number
`enabled`	bool	true	Enable/disable this screen
`width`	number	1280	Window width
`height`	number	720	Window height
`x`	number	0	X position on desktop
`y`	number	0	Y position on desktop
`volume`	number (0-100)	50	Default volume
`quality`	string	"best"	Stream quality
`window_maximized`	bool	false	Start maximized
`primary`	bool	false	Primary screen
`sources`	array	[]	Stream sources (see below)
`sorting`	object	-	Sorting rules
`refresh`	number (sec)	300	Queue refresh interval
`auto_start`	bool	true	Auto-start on launch
`skip_watched_streams`	bool	true	Skip already watched

Source Types

Type	Subtype	Description	Requires
`holodex`	`organization`	Fetch by org name	`name` field
`holodex`	`favorites`	Fetch favorite channels	`favorites.json`
`twitch`	`favorites`	Fetch favorite Twitch channels	`favorites.json`
`twitch`	`vtuber`	Fetch VTuber streams	-
`youtube`	`favorites`	Fetch favorite YouTube channels	`favorites.json`
`youtube`	`popular`	Fetch popular live streams	-

Sorting Fields

Field	Description
`viewerCount`	Sort by viewer count
`startTime`	Sort by start time (oldest first)
`priority`	Sort by priority number
`score`	Sort by favorite score

3. `player.json` – Player Settings

{
  "prefer_streamlink": false,
  "default_quality": "best",
  "default_volume": 50,
  "window_maximized": false,
  "max_streams": 2,
  "auto_start": true,
  "disable_heartbeat": false,
  "force_player": false,
  "logging": {
    "enabled": true,
    "level": "info",
    "max_size_mb": 50,
    "max_files": 5
  },
  "screens": []
}

Field	Type	Default	Description
`prefer_streamlink`	bool	false	Use Streamlink over MPV
`default_quality`	string	"best"	Default stream quality
`default_volume`	number (0-100)	50	Default volume
`window_maximized`	bool	false	Start maximized
`max_streams`	number	4	Max concurrent streams
`auto_start`	bool	true	Auto-start on launch
`disable_heartbeat`	bool	false	Disable health checks
`force_player`	bool	false	Keep player running
`logging`	object	-	Logging configuration

4. `mpv.json` – MPV Player Configuration

{
  "priority": "normal",
  "gpu-context": "auto",
  "cache": "yes",
  "cache-secs": 30,
  "demuxer-max-bytes": 150M,
  "demuxer-max-back-bytes": 50M
}

5. `streamlink.json` – Streamlink Configuration

{
  "path": "/usr/bin/streamlink",
  "options": {
    "player": "mpv",
    "retry-open": 5,
    "retry-streams": 10,
    "hls-segment-threads": 5
  },
  "http_header": {
    "User-Agent": "LiveLink/1.0"
  }
}

6. `filters.json` – Stream Filters

{
  "filters": [
    "members only",
    "member only",
    "membership",
    "unavailable",
    "private",
    "deleted"
  ]
}

Filters out streams whose titles contain these keywords.

7. `config.json` – API Keys (Optional Fallback)

{
  "holodex": { "api_key": "your-holodex-key" },
  "twitch": {
    "client_id": "your-twitch-client-id",
    "client_secret": "your-twitch-client-secret"
  },
  "youtube": { "api_key": "your-youtube-key" }
}

Note: Environment variables override this file.

🖥️ CLI Commands

Stream Management

# List active streams
livelink stream list
livelink stream ls

# List with watch mode (refresh every 5s)
livelink stream list --watch

# Start stream
livelink stream start --url https://twitch.tv/xqc --screen 1 --quality best

# Stop stream
livelink stream stop 1

# Restart stream(s)
livelink stream restart --screen 1
livelink stream restart  # all screens

# Refresh stream data
livelink stream refresh 1
livelink stream refresh  # all screens

Queue Management

# Show queue
livelink queue show 1
livelink queue ls 1

# Add to queue
livelink queue add 1 https://twitch.tv/xqc "XQC Stream"

# Remove from queue (by index)
livelink queue remove 1 2
livelink queue rm 1 1,2,3  # batch remove

# Clear queue
livelink queue clear 1

# Watched streams
livelink queue watched
livelink queue mark-watched https://twitch.tv/xqc
livelink queue clear-watched

Screen Management

# List screens
livelink screen list
livelink screen ls

# Enable/disable screen
livelink screen enable 1
livelink screen disable 1

# Toggle screen
livelink screen toggle 1

Player Control

# Pause/unpause
livelink player pause 1
livelink player pause all

# Set volume
livelink player volume 50 1
livelink player volume 50 all

# Seek
livelink player seek 30 1   # forward 30s
livelink player seek -10 1  # backward 10s

# Set process priority
livelink player priority high

Server Control

# Start server
livelink start

# Stop server
livelink server stop
livelink server stop --all  # stop players too

# Server status
livelink server status

Info & Debug

# List organizations
livelink orgs

# Run diagnostics
livelink diagnostics

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                         CLI / API                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR                           │
│  • Single authority for all stream operations               │
│  • Per-screen mutex locking                                 │
│  • State machine validation                                 │
│  • Max streams enforcement                                  │
└─────────────────────────────────────────────────────────────┘
              │              │              │
              ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Holodex    │  │   Twitch    │  │   YouTube   │
│  Service    │  │   Service   │  │   Service   │
└─────────────┘  └─────────────┘  └─────────────┘
                              │
                              ▼
              ┌─────────────────────────────┐
              │         Queue System        │
              │  • Filter (watched, member) │
              │  • Sort (priority, viewers) │
              └─────────────────────────────┘
                              │
                              ▼
              ┌─────────────────────────────┐
              │        Player Service       │
              │  • MPV IPC control          │
              │  • Health monitoring        │
              │  • Crash recovery           │
              └─────────────────────────────┘

State Machine

Idle ──start──▶ Starting ──success──▶ Playing
  ▲                │                      │
  │                │ error                │ stop
  │                ▼                      ▼
  └─────────────── Error ◀───────────── Stopping
                                                │
                                                ▼
                                              Idle

🔧 Development

Build

cargo build
cargo build --release

Run Tests

cargo test
cargo test -- --nocapture  # with output

Check (without build)

cargo check

Lint

cargo clippy
cargo fmt

📝 Logging

Log levels: error, warn, info, debug, trace

Set via environment:

export LOG_LEVEL=debug
cargo run

Log rotation is automatic (50MB, 5 files).

🐛 Troubleshooting

"Holodex client not initialized"

Missing HOLODEX_API_KEY env var or config.json entry
Service will be disabled, fallback to favorites

"Twitch service not enabled"

Missing TWITCH_CLIENT_ID or TWITCH_CLIENT_SECRET
Service will be disabled

"Max streams reached"

max_streams limit hit (default: 4)
Stop a stream or increase limit in player.json

Streams not starting

Check:

Service is enabled (API key present)
Screen is enabled
Queue has unwatched streams
No duplicate stream already playing

📄 License

MIT

🙏 Credits

Built with:

Tokio - Async runtime
Axum - Web framework
Clap - CLI parser
Serde - Serialization
Tracing - Logging

FilesExpand file tree

README.md

Latest commit

History