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/gwuhaolin/livego 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.

GO — Healthy across all four use cases

• Last commit 5mo ago
• 23+ active contributors
• Distributed ownership (top contributor 21% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago

_{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 gwuhaolin/livego repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gwuhaolin/livego.

What it runs against: a local clone of gwuhaolin/livego — 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 gwuhaolin/livego | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 183 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gwuhaolin/livego. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gwuhaolin/livego.git
#   cd livego
#
# 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 gwuhaolin/livego and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "protocol/rtmp/rtmp.go" \\
  && ok "protocol/rtmp/rtmp.go" \\
  || miss "missing critical file: protocol/rtmp/rtmp.go"
test -f "protocol/hls/hls.go" \\
  && ok "protocol/hls/hls.go" \\
  || miss "missing critical file: protocol/hls/hls.go"
test -f "av/av.go" \\
  && ok "av/av.go" \\
  || miss "missing critical file: av/av.go"
test -f "configure/liveconfig.go" \\
  && ok "configure/liveconfig.go" \\
  || miss "missing critical file: configure/liveconfig.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 183 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~153d)"
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/gwuhaolin/livego"
  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).

livego is a pure-Go live video streaming server that ingests RTMP streams and outputs them via RTMP, HTTP-FLV, and HLS protocols. It handles real-time H.264/AAC/MP3 encoding in FLV and TS container formats, enabling broadcasters to stream to multiple consumer protocols from a single source. Monolithic single-binary design: main.go is the entry point; av/ defines audio/video frame abstractions; protocol/ houses RTMP/AMF/API handlers; container/ implements FLV/TS muxers and demuxers; parser/ extracts H.264/AAC/MP3 metadata; configure/ manages runtime settings; internal services are wired together at boot.

Live streaming platform operators and DevOps engineers who need a lightweight, self-hosted alternative to commercial services like Wowza or Nimble. Users building on-premise streaming infrastructure without external dependencies.

Active but lean: the project has GitHub Actions CI (test.yml, codeql.yml, release.yml), cross-platform binaries via goreleaser, and Docker support. Commit history and dependencies suggest it's production-ready for small-to-medium deployments, though the single-file Makefile and minimal issue tracking suggest it's not heavily maintained relative to its stability.

Low risk operationally but thin maintainer surface: ~13 Go dependencies (go-redis, jwt, logrus, viper) are stable, but the repo shows infrequent updates. No obvious security vulnerabilities visible, though the go.mod targets Go 1.13 (released 2019), which is outdated. The lack of visible issues/discussions suggests either stable usage or low discoverability.

No active development visible in the provided snapshot. The repo appears stable with releases via GitHub Actions, but no recent milestones, PRs, or issue activity are indicated in the file structure alone.

git clone https://github.com/gwuhaolin/livego.git && cd livego && go build

Daily commands: make run (or ./livego). Service listens on :1935 (RTMP), :7001 (HTTP-FLV), :7002 (HLS), :8090 (HTTP API). Config via livego.yaml or CLI flags (--rtmp_addr, --flv_addr, --hls_addr, --api_addr, etc.).

• main.go — Entry point that initializes the live streaming server, loads configuration, and starts protocol handlers (RTMP, HLS, HTTP-FLV)
• protocol/rtmp/rtmp.go — Core RTMP protocol implementation—the primary ingest mechanism for live streams; handles client connections and stream lifecycle
• protocol/hls/hls.go — HLS protocol handler for HTTP Live Streaming output; converts incoming streams to segmented HTTP delivery
• av/av.go — Core audio-video packet abstraction used across all protocol handlers and parsers; defines the unified media frame format
• configure/liveconfig.go — Configuration system that loads and manages server settings from livego.yaml; controls all runtime behavior
• protocol/rtmp/cache/cache.go — GOP (Group of Pictures) cache for RTMP that enables client buffering and keyframe seeking—critical for stream quality
• protocol/hls/cache.go — Segment cache for HLS that manages the sliding window of TS segments available to HTTP clients

Add a new output protocol (e.g., DASH, SRT)

1. Create protocol handler directory under protocol/ with main handler file (e.g., protocol/dash/dash.go) (protocol/dash/dash.go)
2. Implement Source interface (Consume method) to subscribe to streams via av.GetStream() (protocol/dash/source.go)
3. Register handler in main.go via protocol initialization block (example: see protocol/hls/hls.go registration) (main.go)
4. Add config section to livego.yaml for protocol-specific settings (livego.yaml)

Add a new REST API endpoint

1. Add handler function to protocol/api/api.go following existing endpoint patterns (protocol/api/api.go)
2. Register route in api.StartHTTPServer() or corresponding router setup (protocol/api/api.go)
3. Access stream data via av.GetStream(app, stream) to retrieve live AV packets or metadata (av/av.go)

Support a new audio codec (e.g., Opus)

1. Create parser under parser/opus/parser.go to extract frame boundaries and metadata (parser/opus/parser.go)
2. Add AudioOpus type constant to av/av.go CodecType enum (av/av.go)
3. Update container/ts/muxer.go to handle new codec type in TS audio stream initialization (container/ts/muxer.go)
4. Update protocol/amf to encode codec metadata in NetStream.onMetaData event (protocol/amf/metadata.go)

Implement a custom relay or stream filter

1. Create relay handler in protocol/rtmp/rtmprelay/custom_relay.go with Source consumer pattern (protocol/rtmp/rtmprelay/customrelay.go)
2. Implement Consume() to receive av.Packet, apply filter logic, and forward via SetWriter() (protocol/rtmp/rtmprelay/customrelay.go)
3. Register relay in configure/liveconfig.go or main.go during server initialization (configure/liveconfig.go)

• Go / Golang — Lightweight concurrency via goroutines; single binary deployment; excellent network I/O; native support for both server and protocol implementation
• RTMP protocol — Industry-standard for live ingest; universal broadcaster support (OBS, Streamlabs); low-latency frame delivery via chunk streaming
• HLS (HTTP Live Streaming) — Adaptive bitrate streaming; compatible with all browsers and CDNs; segmented delivery enables efficient caching and failover
• Redis (optional dependency) — Distributed state sharing across multiple livego instances; enables clustered relay and multi-server deployments

• GOP-based frame cache instead of timestamp-based ring buffer

  • Why: GOP alignment ensures keyframe synchronization; simplifies client seek and buffering logic
  • Consequence: Requires H.264 SPS/PPS extraction; higher memory for long GOPs; trade memory for predictability

• Synchronous TS segment generation on AV packet arrival

  • Why: Tight coupling ensures HLS segments always reflect latest video; no async race conditions
  • Consequence: Audio frame buffering adds 1–2 frame latency; HLS inherently higher latency than RTMP (~10s vs ~1s)

• Single-threaded stream per app/name; goroutine-per-client

  • Why: Avoids lock contention on hot paths; Go scheduler handles I/O multiplexing
  • Consequence: No intra-stream parallelism; high CPU for many small streams; scales better with few large streams

• FLV container for HTTP-FLV instead of fragmented MP4

  • Why: FLV header-less streaming; lower framing overhead; real-time frame delivery without buffering
  • Consequence: No CDN caching; not HLS-compatible; requires persistent client connection

• Does not implement video transcoding, bitrate adaptation, or quality variation
• Does not provide authentication or authorization beyond basic API token support
• Does not guarantee ordering or deduplication across distributed relay chains
• Does not support Windows Media or proprietary codec containers
• Does not include a web UI or dashboard (API-only control)
• Not optimized for low-latency (<1s) streaming (use SRT or RTMPS for that)

1. channelkey generation: streams require a unique key fetched via GET /control/get?room=X on :8090 before pushing—not obvious from README. 2) Config precedence: CLI flags override livego.yaml; ensure consistent flag order. 3) FLV output: --flv_dir must exist; muxer will write to tmp/{appname}/{key}_{timestamp}.flv without creating parent dirs. 4) HLS https: requires server.key and server.crt in the binary's working directory, not configurable path. 5) Redis caching is optional but changes behavior of session/channel lookup if enabled.

• RTMP (Real Time Messaging Protocol) — The primary ingest protocol for livego; understanding chunking, handshake, and command/data message types is essential for debugging stream failures
• AMF (Action Message Format) — Binary serialization used by RTMP for control messages (connect, createStream, publish); livego has protocol/amf/ codec that handles AMF0/AMF3 encoding/decoding
• FLV (Flash Video Container) — Simple tag-based video container used for HTTP-FLV streaming; livego's container/flv/muxer.go wraps H.264/AAC frames into FLV tags with timestamps
• HLS (HTTP Live Streaming) — Apple's segment-based streaming format; livego generates .m3u8 playlists and TS chunks via container/ts/ for broad device compatibility
• H.264 NAL Units (Network Abstraction Layer) — Fundamental video frame structure; parser/h264/parser.go extracts SPS/PPS (codec config) and IDR/P/B frames needed for muxing into FLV/TS
• MPEG-2 TS (Transport Stream) — Packet format for HLS; livego's container/ts/muxer.go wraps video/audio with PCR timestamps and CRC32 checksums for reliable segmentation
• AAC/MP3 Audio Frames and ADTS — Audio encoding formats handled by parser/aac/ and parser/mp3/; ADTS headers are required for packaging AAC into FLV/TS containers

• arut/nginx-rtmp-module — Industry-standard RTMP server module; livego is a pure-Go alternative attempting to replace this for simpler deployments
• ossrs/srs — Full-featured Go/C++ live streaming server with RTMP/HLS/HTTP-FLV; more mature and feature-rich but heavier than livego
• monkeyWie/gopush-cluster — Go-based push notification and streaming framework; shares Go ecosystem patterns and real-time protocol handling
• golang/go — Core language; livego is Go 1.13+; understanding Go runtime and goroutines critical for async stream handling
• ffmpeg/ffmpeg — De facto tool for pushing streams into livego (ffmpeg -f flv rtmp://...) and consuming output; needed for testing and integration

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 RTMP protocol core components

The repo has protocol/rtmp/core/chunk_stream_test.go but lacks tests for critical RTMP components like cache/cache.go, cache/gop.go, and the core chunk_stream.go edge cases. Given RTMP is a primary protocol for live streaming, robust test coverage is essential for reliability. This would improve code quality and catch regressions early.

• [ ] Add unit tests for protocol/rtmp/cache/cache.go covering GOP cache operations and eviction
• [ ] Add unit tests for protocol/rtmp/cache/gop.go covering keyframe detection and frame ordering
• [ ] Expand protocol/rtmp/core/chunk_stream_test.go with edge cases (malformed chunks, buffer overflows, concurrent access)
• [ ] Ensure test coverage reaches >80% for rtmp package

Add integration tests for HLS streaming pipeline

The HLS implementation (protocol/hls/) has multiple interacting components (cache.go, audio_cache.go, source.go, item.go) but no visible integration tests. Testing the full HLS muxing pipeline end-to-end would catch playlist generation issues, segment timing problems, and audio/video synchronization bugs that unit tests miss.

• [ ] Create protocol/hls/hls_integration_test.go testing segment creation, playlist generation, and cache eviction
• [ ] Test audio_cache.go integration with main cache.go during segment boundaries
• [ ] Verify source.go correctly feeds data through the HLS pipeline
• [ ] Add tests for edge cases like rapid stream starts/stops and bandwidth fluctuations

Add GitHub Actions workflow for Go security scanning and dependency audits

The repo has CodeQL and basic test workflows but lacks automated security scanning for Go-specific issues and dependency vulnerabilities. Given security-critical nature of streaming (SECURITY.md exists), a dedicated security workflow would catch issues like outdated JWT libraries (auth0/go-jwt-middleware, dgrijalva/jwt-go) and unsafe HTTP practices before release.

• [ ] Create .github/workflows/security.yml using gosec action to scan for Go security issues
• [ ] Add dependency audit step using 'go list -json -m all | nancy sleuth' or nancy GitHub Action
• [ ] Configure workflow to fail on critical/high severity findings
• [ ] Document security scanning in SECURITY.md with instructions for contributors

• Add unit tests for container/ts/muxer.go: currently only container/ts/muxer_test.go exists but TS muxing is critical for HLS; test edge cases like CRC32 validation and PCR timestamp wrapping.
• Document the protocol/api/ module: the file list cuts off after protocol/api; add README or godoc examples for HTTP endpoints (likely /control/get, /control/push, etc.) so users understand the control plane.
• Add parser tests for AAC (parser/aac/parser.go) and MP3 (parser/mp3/parser.go): H.264 has parser_test.go but audio parsers do not; add frame extraction and ADTS header validation tests.

Failed to generate security analysis.

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.