If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bililive-go/bililive-go shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 5w ago
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bililive-go/bililive-go repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bililive-go/bililive-go.

What it runs against: a local clone of bililive-go/bililive-go — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bililive-go/bililive-go | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 66 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bililive-go/bililive-go. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bililive-go/bililive-go.git
#   cd bililive-go
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bililive-go/bililive-go and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bililive-go/bililive-go(\\.git)?\\b" \\
  && ok "origin remote is bililive-go/bililive-go" \\
  || miss "origin remote is not bililive-go/bililive-go (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/cmd/bililive/bililive.go" \\
  && ok "src/cmd/bililive/bililive.go" \\
  || miss "missing critical file: src/cmd/bililive/bililive.go"
test -f "src/configs/config.go" \\
  && ok "src/configs/config.go" \\
  || miss "missing critical file: src/configs/config.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f ".github/workflows/release.yaml" \\
  && ok ".github/workflows/release.yaml" \\
  || miss "missing critical file: .github/workflows/release.yaml"
test -f "src/cmd/bililive/internal/init.go" \\
  && ok "src/cmd/bililive/internal/init.go" \\
  || miss "missing critical file: src/cmd/bililive/internal/init.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 66 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~36d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bililive-go/bililive-go"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Bililive-go is a Go-based live stream recording tool that supports 16+ Chinese and international streaming platforms (Bilibili, Douyu, Huya, Twitch, etc.) with a TypeScript/React web UI. It captures live streams to disk, handles multiple concurrent recordings, and provides real-time monitoring via Prometheus metrics and Grafana dashboards. Monorepo with Go backend and TypeScript frontend: main Go code in root (build.go, handlers), web UI in separate TypeScript layer, platform-specific scrapers likely in subdirectories, database migrations via golang-migrate/migrate/v4, and Docker deployment via Dockerfile + docker-compose patterns. Config-driven architecture (config.yml, config.docker.yml) with env override support (.env.example).

Content archivists and automation engineers who need to record live streams across multiple platforms programmatically. Users deploy it as a long-running service (Docker or systemd) to monitor streamer schedules and automatically capture broadcasts without manual intervention.

Actively developed and production-ready. The project has comprehensive CI/CD workflows (tests.yaml, release.yaml, e2e-test.yml), Docker support with multi-platform builds, and SemVer releases. Recent dependency updates (Go 1.25, modernc.org/sqlite v1.42.2) and monitoring integrations (Grafana/Prometheus configs in contrib/) suggest ongoing maintenance.

Moderate complexity with 40+ indirect dependencies; some older pinned versions (gorilla/mux v1.7.4 from 2019). Single primary maintainer pattern (indicated by Bilibili space link in README suggests personal project). Platform-specific parsers for 16+ sites create maintenance burden when sites change their APIs; no obvious deprecation handling visible. However, Docker containerization and CI automation mitigate deployment risk.

Active development on Go 1.25 upgrade, Sentry error tracking integration, and e2e testing infrastructure (e2e-test.yml workflow). Prometheus/Grafana monitoring suite is mature. Multiple GitHub workflows suggest focus on automated testing, code review via Claude, and stale issue management. Recent additions of .agent/ directory with gemini-guide.md and copilot-instructions.md indicate AI-assisted development setup.

git clone https://github.com/bililive-go/bililive-go && cd bililive-go && make (see Makefile for build targets) && ./bililive-go (or docker-compose up if using Docker). Requires Go 1.25+; check .node-version for Node version if building TypeScript frontend.

Daily commands: make build (compiles Go binary) or docker build -f Dockerfile . && docker run -v ./Videos:/app/Videos -p 8080:8080 (exposes web UI). For development: go run build.go or use .vscode/launch.example.json with Delve debugger. Frontend likely built separately with npm/yarn (TypeScript sources present but build output not visible in file list).

• src/cmd/bililive/bililive.go — Main entry point for the application; all contributors must understand how the CLI is initialized and configured.
• src/configs/config.go — Core configuration structure and persistence logic; essential for understanding how all settings flow through the application.
• go.mod — Declares all external dependencies including ffmpeg bindings, HTTP clients, and media handling libraries that are foundational to recording functionality.
• .github/workflows/release.yaml — Defines the build and release pipeline; critical for understanding how binaries are compiled and distributed across platforms.
• src/cmd/bililive/internal/init.go — Initialization sequence for the application including plugin loading and platform registration; sets up the entire live-streaming capture framework.
• Dockerfile — Docker containerization definition showing the runtime environment, ffmpeg integration, and deployment strategy used in production.
• .env.example — Documents all environment variables and configuration options; essential reference for setup and feature enablement.

Add Support for a New Live Streaming Platform

1. Create a new platform/site provider package in src/ following the pattern of existing live platforms (src/cmd/bililive/internal/init.go (register in plugin initialization))
2. Implement the platform-specific stream URL fetching, quality selection, and metadata parsing (new_platform_provider.go (your new file))
3. Register the platform handler in the initialization sequence alongside other platforms (src/cmd/bililive/internal/init.go)
4. Add platform-specific configuration options to config.go if needed (src/configs/config.go)
5. Update README.md to include the new platform in the supported sites table (README.md)

Add a New Configuration Option

1. Define the new field in the configuration struct with YAML tags and comments (src/configs/config.go)
2. Add the field documentation to the config schema generator (src/configs/config_comments.go)
3. Add the option to the example configuration file (config.yml)
4. If a custom type is needed (e.g., byte size), create it in src/configs/ (src/configs/bytesize.go (as reference))
5. Use the configuration value throughout the codebase by injecting via container (src/configs/container.go)

Add a New API Endpoint

1. Create or extend an API handler file in the appropriate src/ package (docs/API.md (reference existing endpoints first))
2. Register the route using Gorilla mux in your handler initialization (src/cmd/bililive/internal/init.go)
3. Document the endpoint with request/response examples (docs/API.md)
4. Add monitoring/metrics if the endpoint is performance-critical (contrib/prometheus/prometheus.yml)

Enable or Disable a Feature Flag

1. Define the feature flag constant in the feature flags configuration (src/configs/feature_flags.go)
2. Add the flag to the main config structure if it affects runtime behavior (src/configs/config.go)
3. Update the environment variable documentation or config file example (.env.example)
4. Use the flag in conditional logic throughout the codebase via dependency injection (src/configs/container.go)

• Go 1.25 — Provides efficient concurrency primitives (goroutines) essential for managing multiple simultaneous stream recordings; fast compilation and cross-platform binary building.
• FFmpeg (via subprocess) — Industry-standard, battle-tested multimedia framework supporting RTMP, HLS, HTTP streaming protocols and codec transcoding needed for robust live recording.
• Gorilla Mux — Lightweight HTTP router for REST API endpoints; enables monitoring, configuration, and control APIs without heavy framework overhead.
• Prometheus Client — Observability-first metrics collection; integrates with Grafana for real-time dashboard visualization of recording health and performance.
• Docker — Enables easy deployment across heterogeneous infrastructure (NAS, VPS, Kubernetes) without dependency management complexity.

• Process-based FFmpeg execution rather than linked library binding

  • Why: Avoids complex FFmpeg C bindings, reduces maintenance burden, allows independent FFmpeg version management and updates.
  • Consequence: Slightly higher inter-process overhead and no programmatic stream format introspection; requires FFmpeg in the runtime environment.

• YAML-based configuration rather than UI-first configuration panel

  • Why: Simplifies deployment for server/headless environments, enables version control of configurations, reduces feature scope.
  • Consequence: Users must edit text files manually; steeper learning curve for non-technical users; mitigated by web dashboard provided by API.

• Plugin-based platform support (via code registration at init time)

  • Why: Allows modular addition of new platforms without recompilation; clear separation of platform-specific logic.
  • Consequence: Each new platform requires code change and recompilation; not a true plugin system with dynamic loading.

• Real-time stream transcoding or quality adaptation (FFmpeg runs as-is; output format determined at startup)
• Cross-platform GUI client (web dashboard provided but no native desktop application)
• Live stream playback or viewer functionality (recording and archival only)
• Automatic thumbnail/preview generation from recordings
• Complex scheduling beyond simple cron via external tools
• Multi-user access control or role-based permissions (assumes single operator or trusted network)

1. Platform parsers are fragile: Bilibili and Douyin require cookies (.cookie support noted in README) which must be manually refreshed when they expire. 2) Database migrations are sequential (golang-migrate)—rolling back with schema changes can be destructive; test migrations locally first. 3) SystemD service assumes /home/bililive-go working directory by default (check contrib/systemd/)—paths may not match your setup. 4) Concurrent recording limits not visible in config—check gopsutil integration for resource constraints. 5) Docker build references specific Go/Node versions (.node-version, Go 1.25); mismatches cause subtle build failures.

• Live Stream Protocol Parsers (RTMP, HLS, DASH) — Each platform (Bilibili, Douyu, etc.) exposes streams via different protocols; bililive-go must parse platform-specific API responses to extract the correct stream URL and headers before passing to ffmpeg.
• Prometheus Metrics & Time-Series Monitoring — bililive-go exports metrics via prometheus/client_golang (recording duration, bytes written, API errors) to Prometheus, visualized in Grafana; understanding scrape intervals and retention is critical for production deployment.
• Database Migrations (golang-migrate/migrate) — Recording metadata (streamer IDs, timestamps, file paths) are persisted in SQLite; migrations version the schema—breaking changes require planning to avoid data loss on rolling updates.
• Graceful Shutdown & Signal Handling — Long-running recording processes must finish in-flight streams before exiting; improper shutdown handling causes truncated video files—requires context cancellation and goroutine coordination patterns.
• Container Orchestration (Docker & systemd) — bililive-go is deployed as both Docker containers and systemd services; understanding service dependencies, resource limits, and restart policies is essential for reliable long-term operation.
• Web Scraping & JavaScript Rendering (otto/JS execution) — Some platforms (Douyin, Bilibili) require executing JavaScript to extract stream URLs from DOM; bililive-go imports robertkrimen/otto for JS evaluation—understanding CORS, cookies, and anti-scraping bypasses is required for parser maintenance.
• Concurrent Recording with Resource Pooling — Multiple streamers may go live simultaneously; bililive-go must manage goroutine pools, CPU/disk throttling (gopsutil), and queue prioritization to avoid resource exhaustion on limited hardware.

• streamlink/streamlink — Industry-standard multi-platform stream extraction library in Python; bililive-go solves the same problem in Go with built-in recording and web UI, making it more deployment-friendly for 24/7 archival.
• yt-dlp/yt-dlp — Universal video downloader supporting YouTube, Twitch, and 1500+ sites; bililive-go is lighter-weight and specifically optimized for live recording with continuous monitoring rather than one-shot downloads.
• mpv-player/mpv — Media player and stream processor used by streamlink; bililive-go uses media handling libraries (bluenviron/mediacommon) to achieve similar stream processing without requiring external player dependencies.
• ProxmoxVE/pbs — Enterprise backup system with Prometheus metrics and systemd integration; architectural patterns (migrations, monitoring, containerization) are similar, making bililive-go suitable for large-scale archival deployments.
• jqlang/jq — JSON query tool; bililive-go uses tidwall/gjson for extracting stream URLs from platform APIs—understanding JSON path queries is essential for adding new platform parsers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for core recording logic in pkg/

The repo has CI workflows (tests.yaml) and uses testify, but the file structure shows no visible test files in the partial listing. Given this is a critical live streaming recorder, the core recording, stream parsing, and output handling logic needs high test coverage. This would catch regressions in platform integrations and file handling.

• [ ] Identify untested packages in pkg/ directory (likely pkg/recorders/ and pkg/nfo/ based on typical Go project structure)
• [ ] Create *_test.go files for stream parsing and HLS/DASH downloader packages
• [ ] Add mock implementations using go.uber.org/mock (already in dependencies)
• [ ] Ensure tests cover platform-specific edge cases mentioned in docs/FAQ.md
• [ ] Run make test locally and update coverage thresholds in .golangci.yml

Add E2E tests for Docker deployment workflows

The repo has Dockerfile, docker-compose.yml, and Synology-specific setup docs (docs/Synology-related.md), but e2e-test.yml workflow exists without visible test implementations. Docker deployment is critical for accessibility. Adding realistic E2E tests would validate config.docker.yml and systemd integration (contrib/systemd/).

• [ ] Expand .github/workflows/e2e-test.yml to test docker-compose.yml startup and health checks
• [ ] Add test scenarios: docker build, config loading from config.docker.yml, prometheus metrics endpoint verification
• [ ] Create simple integration test that validates the recorder starts without crashing on mock Bilibili endpoints
• [ ] Document expected test results in docs/FAQ.md for troubleshooting deployment issues
• [ ] Test against both standard Docker and docker-compose setups mentioned in Dockerfile.build-and-run

Complete API documentation with request/response examples for docs/API.md

docs/API.md exists but the README snippet doesn't detail the HTTP API. Given there's a .github/copilot-instructions.md and gorilla/mux in dependencies, the service exposes HTTP endpoints. Contributors need concrete examples to build integrations. This blocks external tool integration.

• [ ] Review gorilla/mux route handlers in source code to extract all HTTP endpoints
• [ ] Document endpoints in docs/API.md with method (GET/POST), path, request body schema, and response examples
• [ ] Add curl examples for common operations (list recordings, start/stop recorder, fetch metrics)
• [ ] Cross-reference prometheus metrics from contrib/prometheus/prometheus.yml in the metrics section
• [ ] Link from README.md to docs/API.md in a 'Integration' or 'Developer Guide' section

• Add test coverage for platform parser handlers: The README lists 16+ sites but test files (stretchr/testify imported) don't show exhaustive parser tests—write unit tests for 3 parsers (Douyu, Huya, OPENREC) that mock API responses and verify stream URL extraction.
• Document recording quality profiles in README: config.yml exists but README lacks examples of video codec/bitrate/resolution settings; add a 'Configuration Guide' section with 3 sample configs (HD, SD, audio-only) and explain ffmpeg integration.
• Add health check endpoint to web UI: Prometheus metrics are exported (prometheus/client_golang imported) but no /health endpoint visible for load balancer integration; implement liveness/readiness probes returning JSON status of recording threads and database connectivity.

• High · Outdated and Vulnerable Go Dependencies — go.mod. Multiple dependencies have known security vulnerabilities and are significantly outdated. Notable examples: gorilla/mux v1.7.4 (released 2019, current is v1.8+), prometheus/client_golang v1.11.0 (released 2021), golang.org/x/net v0.48.0 and golang.org/x/sys v0.39.0 which are several versions behind current. These packages may contain unpatched CVEs. Fix: Run 'go get -u ./...' to update all dependencies to latest versions. Review go.mod for any major version constraints that prevent updates. Implement automated dependency scanning with tools like 'go list -json -m all | nancy' or GitHub's Dependabot.
• High · Insecure Dependency: Otto JavaScript Engine — go.mod - github.com/robertkrimen/otto. Package github.com/robertkrimen/otto v0.0.0-20191219234010-c382bd3c16ff is abandoned (last commit 2019) and may contain unpatched vulnerabilities. If used to execute user-supplied JavaScript, this could enable code injection attacks. Fix: Evaluate if Otto usage is necessary. If JavaScript execution is required, consider goja (actively maintained) or implement strict sandboxing. If not in use, remove the dependency entirely.
• High · Unvalidated External Version Check URL — .env.example, VERSION_API_URL configuration. The .env.example shows VERSION_API_URL configuration for auto-upgrade functionality. If this URL is not properly validated and pinned, or if version comparison logic is flawed, attackers could perform man-in-the-middle attacks or supply malicious versions for download. Fix: Implement HTTPS-only pinning for version check URLs. Validate SSL certificates. Use signed releases with GPG verification. Implement version comparison integrity checks. Never execute or apply version updates without cryptographic verification.
• High · Debug Tooling in Production Dependencies — go.mod - delve and gopls. The go.mod includes github.com/go-delve/delve v1.26.0 (a debugger) and golang.org/x/tools/gopls v0.21.0 (language server). These should never be in production builds as they expose internal application state and enable runtime code execution. Fix: Move these to a separate 'tools.go' file with build tag 'tools' or to 'go get' installation only in development. Ensure production builds exclude these packages using build constraints.
• Medium · Hardcoded Default Docker User Permissions — Dockerfile - PUID=0 PGID=0. Dockerfile sets PUID=0 PGID=0 by default, meaning the container runs as root. This violates the principle of least privilege and increases blast radius if the application is compromised. Fix: Create a non-root user in the Dockerfile (e.g., bililive:bililive with UID 1000). Set PUID and PGID to non-zero values. Use USER directive to drop privileges. Allow PUID/PGID override via environment variables for flexibility.
• Medium · Missing Network Security in docker-compose.yml — docker-compose.yml. The docker-compose configuration exposes port 8080 without network segmentation or ingress controls. No restart policy conditions are defined properly, and volumes are mounted with default permissions that may be too permissive. Fix: Define a custom network with 'networks' section. Restrict port 8080 to 127.0.0.1:8080 unless external access is required. Use read-only mounts where possible. Implement proper volume ownership. Add restart policy conditions.
• Medium · Insecure SMTP Configuration in Dependencies — go.mod - gopkg.in/gomail.v2. gopkg.in/gomail.v2 dependency is from 2016 and lacks TLS/STARTTLS enforcement options. Email notifications (likely for alerts) could transmit sensitive data unencrypted if misconfigured. Fix: Review all email notification code for TLS usage. Upgrade to a maintained mail library if possible. Enforce TLS via configuration validation. Never store SMTP credentials in code or unencrypted configs.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.