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/iawia002/lux 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 the board

• Last commit 6w ago
• 30+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

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

What it runs against: a local clone of iawia002/lux — 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 iawia002/lux | 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 ≤ 71 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "iawia002/lux(\\.git)?\\b" \\
  && ok "origin remote is iawia002/lux" \\
  || miss "origin remote is not iawia002/lux (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 "app/app.go" \\
  && ok "app/app.go" \\
  || miss "missing critical file: app/app.go"
test -f "app/register.go" \\
  && ok "app/register.go" \\
  || miss "missing critical file: app/register.go"
test -f "downloader/downloader.go" \\
  && ok "downloader/downloader.go" \\
  || miss "missing critical file: downloader/downloader.go"
test -f "extractors/extractors.go" \\
  && ok "extractors/extractors.go" \\
  || miss "missing critical file: extractors/extractors.go"
test -f "downloader/types.go" \\
  && ok "downloader/types.go" \\
  || miss "missing critical file: downloader/types.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 71 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~41d)"
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/iawia002/lux"
  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).

Lux is a fast command-line video downloader written in Go that supports 50+ video platforms (YouTube, TikTok, Bilibili, Instagram, Twitter, etc.) with features like multi-threaded downloads, playlist support, automatic retries, and cookie/proxy handling. It acts as a universal extractor and downloader that parses video metadata and streams directly without relying on external tools except FFmpeg for merging. Monolithic CLI application: main entry in cmd/lux with platform extractors as pluggable packages (likely pkg/downloader or pkg/extractors). Each video platform (YouTube, Bilibili, TikTok, etc.) gets its own extractor package that implements a common interface. Workflow files (stream_*.yml) run platform-specific integration tests in CI.

Go developers and end-users who need a scriptable, high-performance video download tool that works across Chinese and international video platforms. DevOps engineers building CI/CD pipelines for media processing, and contributors extending support to new video sites.

Actively maintained and production-ready: 50+ platforms supported via individual workflow files (stream_*.yml), comprehensive GitHub Actions CI setup (ci.yml, goreleaser.yml), and coverage tracking via Codecov. Recent commits and ongoing workflows indicate active development, though it's a single-maintainer project.

Moderate risk from tight coupling to site-specific scrapers (each platform in separate Go packages) that break when sites change HTML/APIs; 40+ stream workflows suggest high maintenance burden if platforms update frequently. Dependency on goja (JavaScript engine) and goquery (web scraping) adds complexity. Single maintainer (iawia002) is a concentration risk for critical fixes.

Continuous testing and validation of 50+ video platforms via individual GitHub Actions workflows (stream_youtube.yml, stream_tiktok.yml, stream_bilibili.yml, etc.). Recent Go 1.24 upgrade in go.mod and active dependency management (goja 0.0.0-20250624, PuerkitoBio/goquery 1.10.3). No visible recent major feature additions, primarily maintenance-focused.

git clone https://github.com/iawia002/lux.git
cd lux
go install ./cmd/lux
lux 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'

Requires FFmpeg installed separately via your package manager (brew install ffmpeg on macOS).

Daily commands:

go run ./cmd/lux <VIDEO_URL>
# With options:
go run ./cmd/lux -o ~/Downloads -c cookies.txt -p 'http://proxy:8080' <URL>
# Debug mode:
go run ./cmd/lux -d <URL>

• app/app.go — Main application entry point orchestrating CLI setup and the video download workflow; every contributor must understand the top-level request flow here
• app/register.go — Site extractor registration mechanism; essential for understanding how new video platform support is plugged into the system
• downloader/downloader.go — Core download engine handling concurrent segment fetching, merging, and error handling; critical for performance and reliability
• extractors/extractors.go — Extractor interface definition and dispatch logic; load-bearing abstraction that defines the contract all platform extractors must implement
• downloader/types.go — Data structures for streams, formats, and download metadata; defines the information model flowing through the entire system
• .github/workflows/ci.yml — CI/CD pipeline defining test and build automation; governs code quality gates and release processes

• CLI Router (app/app.go + app/register.go) (urfave/cli/v2, Go flag parsing) — Parses command-line arguments, dispatches URL to correct extractor, orchestrates download request
  • Failure mode: Unsupported site, malformed URL → user error message; config load failure → graceful exit
• Extractor interface & implementations (extractors/) (goquery, goja, gocolly, HTTP client, JSON parsing) — Discovers video streams, formats, and metadata from a specific platform using site-specific logic (HTML parsing, API calls, JS execution)
  • Failure mode: Page changed, API blocked, JS error → returns empty stream list; network error → retry or fail extraction
• Download engine (downloader/downloader.go) — Orchestrates parallel segment/chunk downloads, selects quality, merges segments into final file, handles retries and progress reporting

Add support for a new video platform

1. Create a new extractor package directory following the existing pattern (e.g., extractors/newsite/newsite.go) (extractors/newsite/newsite.go)
2. Implement the Extractor interface methods (Extract, Name, Limit) with platform-specific URL parsing and stream discovery logic (extractors/newsite/newsite.go)
3. Define platform-specific types in a types.go file if needed for complex data structures (extractors/newsite/types.go)
4. Register the new extractor in the registry by adding an import and init call (app/register.go)
5. Add unit tests following the naming pattern extractors/newsite/newsite_test.go, testing URL detection and stream extraction (extractors/newsite/newsite_test.go)

Modify download behavior or add a new output format

1. Update the Stream and Format types to include new quality/codec options (downloader/types.go)
2. Modify the downloader logic to handle the new format selection or merging strategy (downloader/downloader.go)
3. Update output filename logic and file handling in utility functions (downloader/utils.go)
4. Add integration tests to verify download and merge behavior end-to-end (downloader/downloader_test.go)

Add a new command-line flag or option

1. Define the flag in the CLI setup within app.go, adding help text and default values (app/app.go)
2. Pass the flag value through to the downloader or extractor configuration layers (config/config.go)
3. Update downloader or extractor logic to respect the new flag in download/extraction workflow (downloader/downloader.go)

• Go — Compiled language with built-in concurrency (goroutines), fast startup, single binary distribution, ideal for CLI tools and concurrent HTTP fetching
• urfave/cli/v2 — Provides structured command-line argument parsing, help text generation, and subcommand support with minimal boilerplate
• goja (JavaScript VM) — Executes site-specific JavaScript for decryption, signature generation, and dynamic stream discovery (e.g., Douyin sign.js)
• PuerkitoBio/goquery — jQuery-like HTML parsing for extracting metadata from page sources where APIs are unavailable
• gocolly/colly — Web scraping framework with automatic retry, rate limiting, and cookie management for complex extraction scenarios
• cheggaaa/pb (progress bar) — Provides real-time download progress visualization to users during potentially long downloads

• Plugin-based extractor registration via app/register.go rather than dynamic loading

  • Why: Simplifies distribution (single binary), enables compile-time type checking, avoids runtime dependency management
  • Consequence: Adding a new site requires code change and recompile; cannot hot-load new extractors at runtime

• Sequential extractor matching (URL pattern → correct extractor) rather than parallel probing

  • Why: Predictable latency, no wasted HTTP calls, clear user feedback on unsupported sites
  • Consequence: Must maintain accurate URL patterns for each extractor; ambiguous patterns could cause misrouting

• Synchronous download orchestration with goroutine worker pools rather than async/await model

  • Why: Go's goroutines are lightweight (~2KB) and composable; enables simple concurrent segment fetching without callback complexity
  • Consequence: Context management and cancellation must be explicit; goroutine leaks possible if cleanup is omitted

• In-memory buffering of downloaded segments before merging

  • Why: Faster merging, simpler error handling (can retry from buffer), avoids multiple disk I/O passes
  • Consequence: High memory usage for large videos; not suitable for embedded/low-memory devices

• Real-time streaming playback (extracts and downloads only, does not play video)
• Cross-platform GUI (CLI-only tool, no web or desktop UI)
• DRM/DASH content support beyond plaintext segments (focuses on accessible, unprotected streams)
• Video re-encoding or format conversion (downloads as-is without transcoding)
• Cloud synchronization or remote storage integration (local filesystem only)
• User authentication or credential storage beyond HTTP cookies

1. FFmpeg external dependency: Downloads work without FFmpeg, but merging multiple streams into a single file fails silently if FFmpeg not in PATH. 2. Platform-specific cookies/auth: Some extractors (Bilibili, iQIYI, VIP content) require session cookies passed via -c flag; no built-in login flow. 3. JavaScript evaluation latency: goja (pure Go JS engine) is slower than Node.js; may timeout on sites with heavy JS obfuscation. 4. Geo-blocking: Many extractors fail outside specific regions (Chinese platforms expect CN IP); use -p proxy workaround. 5. Fragile scraping: HTML selectors in goquery queries break instantly when sites update; contributors must validate via stream_*.yml workflows.

• Web Scraping & DOM Parsing — Core mechanism: extractors use goquery (CSS selectors) and gocolly (HTTP + parsing pipeline) to parse HTML and extract video stream URLs; understanding CSS selectors and DOM traversal is essential to debug extractor failures
• JavaScript Obfuscation & goja VM Execution — Many video platforms (YouTube, Bilibili) obfuscate stream URLs in JavaScript; Lux uses goja (pure Go JS runtime) to execute and extract URLs, requiring knowledge of JS evaluation within Go
• Adaptive Streaming (HLS/DASH) — Modern video platforms use HTTP Live Streaming (HLS) or DASH, serving video as segmented chunks; extractors must parse m3u8/mpd manifests and download segments, then FFmpeg merges them
• HTTP Client Fingerprinting & Bot Detection Evasion — Sites block downloads by detecting User-Agent, IP patterns, request frequency; Lux uses fake-useragent and cookie/proxy support to evade detection—critical for reliability
• Plugin Architecture via Interface-based Extractors — Each video platform is a pluggable extractor package implementing a common Extractor interface; understanding this pattern is key to adding new platforms without modifying core code
• Concurrent Downloads & Multi-threading — Lux supports multi-threaded segment/chunk downloads via goroutines; understanding Go's concurrency model (goroutines, channels, sync.WaitGroup) is essential for optimizing download speed
• Container-based Integration Testing (GitHub Actions Workflows) — 50+ stream_*.yml workflows validate each platform's extractor against live sites on a schedule; understanding CI/CD patterns ensures new extractors are properly tested

• yt-dlp/yt-dlp — Industry-standard Python video downloader supporting 1000+ sites; Lux is Go-based alternative with simpler codebase but narrower platform coverage
• rg3/youtube-dl — Original Python video downloader that yt-dlp forked from; Lux reimplements similar functionality in Go for better performance
• nicolaka/media-grab — Go-based alternative focused on audio extraction; shares similar architecture of platform-specific extractors
• go-echarts/go-echarts — Unrelated but exemplifies Go library ecosystem; developers familiar with Go package patterns will recognize Lux's extractor plugin design
• junegunn/fzf — Exemplar of well-engineered single-purpose Go CLI tool; Lux follows similar minimalist, high-performance Go CLI patterns

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 downloader/downloader.go

The downloader package is a critical core component, but downloader_test.go appears minimal based on the file structure. With 50+ extractors relying on this package, robust tests would catch regressions and ensure reliability across different video sources. This is especially important given the complexity of handling various video formats and streaming protocols.

• [ ] Review downloader/downloader.go and downloader/downloader_test.go to identify untested functions and edge cases
• [ ] Add unit tests for concurrent download scenarios, error handling, retry logic, and progress tracking
• [ ] Add integration test fixtures that mock responses from different extractor types (e.g., m3u8 playlists, progressive downloads)
• [ ] Ensure test coverage reaches >80% for the downloader package and update codecov.yml expectations accordingly

Create GitHub Actions workflow for automated extractor health checks

The repo has 50+ individual stream_*.yml workflows for testing site extractors, but there's no unified workflow to detect broken extractors or stale dependencies across all of them. Adding a meta-workflow that runs weekly health checks and reports extractor status would help identify which extractors are currently failing and need maintenance, reducing the burden on maintainers.

• [ ] Create .github/workflows/extractor_health_check.yml that runs on a schedule (e.g., weekly)
• [ ] Implement a Go script in the root or app directory that iterates through all extractors in extractors/ and attempts to fetch metadata
• [ ] Generate a summary report indicating which extractors are currently functional vs. broken (output as GitHub Actions summary or artifact)
• [ ] Add optional notification step to post a comment on a designated issue with results

Add missing extractor test files and normalize test structure

The file listing shows some extractors have _test.go files (acfun, bcy) but many don't. Given the number of extractors (50+), a systematic approach to adding basic unit tests for each would improve code quality and provide a template for new contributors. This also serves as documentation for how each extractor is expected to work.

• [ ] Audit extractors/ directory to identify which extractors lack corresponding _test.go files
• [ ] Create a test template (e.g., extractors/_template/_template_test.go) that tests common patterns: URL matching, metadata extraction, and stream parsing
• [ ] Generate missing _test.go files for high-priority extractors (YouTube, TikTok, Instagram, Twitter/X based on complexity and popularity)
• [ ] Document the testing pattern in CONTRIBUTING.md with examples to guide future contributors adding new extractors

1. Add fallback User-Agent rotation: Extend fake-useragent package usage in pkg/request/request.go to rotate across browser UA strings per request, improving resilience to UA-based blocking (small, isolated change). 2. Add unit tests for existing extractors: Many pkg/extractors/*/ packages likely lack tests; add _test.go files with mock HTTP responses to validate parsing logic without hitting live sites. 3. Document platform-specific quirks: Create a docs/platforms/ directory with markdown files for each extractor explaining auth requirements, geo-blocking, throttling, and cookie format (low-risk, high-value docs contribution).

• High · Deprecated JavaScript Runtime Library — go.mod - github.com/robertkrimen/otto v0.5.1. The codebase uses github.com/robertkrimen/otto v0.5.1, which is an outdated and no longer actively maintained JavaScript runtime for Go. This library has known security vulnerabilities and may not receive security patches. Fix: Consider replacing with a more actively maintained JavaScript runtime like github.com/dop251/goja (already in use) or evaluating if JavaScript execution can be eliminated entirely.
• High · Use of Deprecated otto Library Alongside goja — go.mod - dependencies section. The project includes both github.com/robertkrimen/otto and github.com/dop251/goja as JavaScript runtime options. Otto is deprecated and known to have security issues. Having multiple JS runtimes increases attack surface. Fix: Remove github.com/robertkrimen/otto dependency and standardize on goja for all JavaScript execution needs.
• Medium · Potential Code Injection via JavaScript Evaluation — extractors/ directory structure - particularly douyin/sign.js usage pattern. The presence of multiple JavaScript runtime libraries (goja, otto) combined with extractors that parse web content suggests potential for code injection attacks if user-controlled content is evaluated as JavaScript without proper sanitization. Fix: Implement strict input validation and sandboxing for any JavaScript evaluation. Ensure web-scraped content is never directly executed as code. Use allowlists for dynamic code execution.
• Medium · Potential SSRF via Web Scraping — extractors/ - all extractor modules using gocolly/colly. The codebase includes gocolly (web scraper) and multiple extractors for various video platforms. These can be exploited for Server-Side Request Forgery (SSRF) attacks if URLs are not properly validated before making requests. Fix: Implement strict URL validation, domain whitelisting where possible, and disable requests to private/internal IP ranges (127.0.0.1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.).
• Medium · User-Agent Spoofing Library — go.mod - github.com/EDDYCJY/fake-useragent v0.2.0. The dependency github.com/EDDYCJY/fake-useragent is used for generating fake user agents, which could be used to bypass security controls, rate limiting, or detection mechanisms of target services. Fix: Ensure this library is only used for legitimate web scraping with proper respect for robots.txt and terms of service. Implement rate limiting and respect for server-side restrictions.
• Medium · Insecure Cookie Handling — go.mod - github.com/MercuryEngineering/CookieMonster v0.0.0-20180304172713-1584578b3403. The dependency github.com/MercuryEngineering/CookieMonster suggests custom cookie manipulation. Combined with video downloading from multiple sites, this could lead to credential exposure if cookies containing authentication tokens are logged or stored insecurely. Fix: Ensure cookies are handled securely - never log authentication cookies, use secure storage, and implement proper session management. Validate the CookieMonster library implementation.
• Low · Outdated Deprecated Package — go.mod - github.com/pkg/errors v0.9.1. The github.com/pkg/errors v0.9.1 is a legacy error handling library. Go 1.13+ provides built-in error wrapping via fmt.Errorf and errors.Is/As. Fix: Migrate to Go's standard library error handling (errors.New, errors.Is, errors.As, fmt.Errorf with %w) and remove the pkg/errors dependency.
• Low · Missing Security Headers Configuration — app/ - app.go configuration. No evidence of security headers configuration (CSP, X-Frame-Options, etc.) in the provided file structure. If this tool exposes any web interface, security headers should be implemented. Fix: If any HTTP server is exposed, configure appropriate security headers. Document security best practices for CLI usage.

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.