feat: Twitch VOD download support

[biodrone]

Summary

• Adds per-channel vod: true config toggle to download Twitch past broadcasts instead of live streams
• New GetVods gRPC RPC enumerates VODs via yt-dlp; existing GetStream resolves each VOD URL through Streamlink/yt-dlp
• SQLite database tracks download state with status lifecycle (downloading/completed/failed) and stale threshold detection for crash recovery
• Separate -vod-out / -vod-move flags allow routing VOD downloads to different directories than live streams
• VOD files use {user}_vod_{id}_{title}.mp4 naming with stream copy (no re-encoding)

Test plan

• TestParseConfig_VODFields — VOD config parsing
• TestVodDB_InitAndClose — DB creation
• TestVodDB_FullLifecycle — started → completed lifecycle
• TestVodDB_FailedVODIsRetried — failed VODs are retried
• TestVodDB_StaleDownloadIsRetried — stale downloads detected and retried
• TestVodDB_DifferentVODsAreIndependent — VOD isolation
• Integration test: VOD download phase added to tests/integration/run.sh
• Manual: configure a channel with vod: true and verify VODs download and are tracked in DB

Summary by CodeRabbit

Release Notes

• New Features

  • Added VOD (Video On Demand) support for Twitch with per-channel configuration options (vod and vod_limit)
  • Added CLI flags -data, -vod-out, and -vod-move for managing VOD downloads and persistent state tracking
  • VOD status is now persistently tracked to avoid duplicate downloads

• Documentation

  • Updated documentation with VOD configuration and usage guidance

• Dependencies

  • Updated Go, Python, and gRPC dependencies to newer versions
  • Bumped project version to 3.6.0

• Chores

  • Updated GitHub Actions workflows to newer major versions

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6aee85fa-26c8-474a-a2ed-43f5d68d6c6c

📥 Commits

Reviewing files that changed from the base of the PR and between 9f841c0 and af000db.

⛔ Files ignored due to path filters (6)

• go.sum is excluded by !**/*.sum
• node_modules/.package-lock.json is excluded by !**/node_modules/**
• package-lock.json is excluded by !**/package-lock.json
• protos/stream.pb.go is excluded by !**/*.pb.go
• protos/stream_grpc.pb.go is excluded by !**/*.pb.go
• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (23)

• .github/workflows/deploy_master.yml
• .github/workflows/deploy_staging.yml
• .github/workflows/test.yml
• .github/workflows/update-actions.yml
• CHANGELOG.md
• README.md
• config.go
• config/config.yml.example
• config_reader_test.go
• download_stream.go
• entrypoint_client.sh
• go.mod
• grpc_client.go
• protos/stream.proto
• pyproject.toml
• stream_pb2.py
• stream_pb2_grpc.py
• streamdl.go
• streamdl_proto_srv.py
• tests/integration/docker-compose.integration.yml
• tests/integration/run.sh
• vod_db.go
• vod_db_test.go

---

📝 Walkthrough

Walkthrough

This PR implements a VOD (Video On Demand) download feature for Twitch, including SQLite-backed download state tracking, gRPC service extension, CLI/config support, and integration tests. GitHub Actions workflows are updated to newer major versions, and Python/Go dependencies are bumped.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflows .github/workflows/deploy_master.yml, deploy_staging.yml, test.yml, update-actions.yml	Updated multiple third-party GitHub Actions to newer major versions: actions/checkout v4→v6, actions/setup-node v4→v6, actions/setup-go v5→v6, Docker actions (setup-qemu, setup-buildx, login) v3→v4, github/codeql-action/upload-sarif v3→v4, and WyriHaximus/github-action-get-previous-tag v1→v2. No workflow logic changes.
Documentation & Configuration README.md, CHANGELOG.md, config.go, config/config.yml.example	Added VOD download feature documentation (new vod and vod_limit YAML fields, -data/-vod-out/-vod-move CLI flags). Extended Streamer config struct with VOD and VODLimit fields. Added v3.6.0 changelog entry.
VOD Database & Persistence vod_db.go, vod_db_test.go	Introduced VodDB type backed by SQLite with downloaded_vods table. Provides initialization, state lifecycle methods (ShouldDownloadVOD, MarkVODStarted/Completed/Failed), and stale-download retry logic. Five unit tests validate initialization, full lifecycle, failure/retry scenarios, and per-VOD independence.
Download Stream Logic download_stream.go	Added sanitizeFilename() for safe VOD title filesystem usage and new downloadVOD() function that builds output/move paths, manages VOD state in database, launches FFmpeg with stream-copy args (-c:v copy -c:a copy -movflags +faststart), and implements graceful shutdown via control-channel-to-SIGINT forwarding.
gRPC Protocol & Service protos/stream.proto, grpc_client.go, streamdl_proto_srv.py	Extended Stream service with new GetVods RPC. Added VodRequest, VodInfo, VodResponse protobuf messages. Implemented Go client getVods() with gRPC error mapping (NotFound→404, ResourceExhausted→429). Added Python server method GetVods with yt_dlp integration for VOD discovery and error handling.
Generated gRPC Code stream_pb2.py, stream_pb2_grpc.py	Regenerated protobuf Python bindings for new GetVods method. Updated module metadata, added gRPC version compatibility checks, extended StreamStub/StreamServicer with GetVods handlers, refactored descriptor-building calls, and added experimental client/server method wrappers.
Main Application & Config Parsing streamdl.go, config_reader_test.go	Added CLI flags (-data, -vod-out, -vod-move) with sensible defaults. Initialized persistent VOD database at startup. Refactored per-streamer loop to branch on streamer.VOD: VOD mode queries database for stale/pending downloads, resolves URLs via gRPC, spawns downloadVOD tasks; live mode preserved with reduced 60s→30s retry sleep. Added test TestParseConfig_VODFields to validate YAML config parsing.
Entrypoint & Dependencies entrypoint_client.sh, go.mod, pyproject.toml	Extended shell entrypoint to create /app/data directory and update ownership attempts. Bumped Go indirect dependencies (golang.org/x/sys, added SQLite/modern.org modules). Updated Python version to 3.6.0 and tightened runtime constraints: curl-cffi≥0.15.0, grpcio≥1.80.0, streamlink≥8.3.0, yt-dlp≥2026.3.17; added grpcio-tools≥1.71.2 dev dependency.
Integration Tests tests/integration/docker-compose.integration.yml, tests/integration/run.sh	Added /app/data volume mount to test client service. Extended integration test suite with Phase 5: VOD download test that writes VOD-enabled config, restarts client, polls for *_vod_* output files (180s timeout, 5s intervals), and validates file integrity (≥1000 bytes). Updated live-stream test messaging for clarity.

Sequence Diagram(s)

sequenceDiagram
    participant Client as StreamDL Client
    participant CtxMgr as Control Logic<br/>(streamdl.go)
    participant GrpcSrv as gRPC Server<br/>(Python)
    participant YtDlp as yt-dlp
    participant VodDB as SQLite DB<br/>(VOD State)
    participant FFmpeg as FFmpeg Process
    participant FileIO as Output Directories

    CtxMgr->>GrpcSrv: getVods(site, user, limit)
    GrpcSrv->>YtDlp: extract_info(url, download=False)
    YtDlp-->>GrpcSrv: VOD metadata list
    GrpcSrv-->>CtxMgr: [VodResult{id, title, ...}]

    loop For each discovered VOD
        CtxMgr->>VodDB: ShouldDownloadVOD(vodID, staleThreshold)
        alt VOD not yet downloaded
            VodDB-->>CtxMgr: true (proceed)
            CtxMgr->>GrpcSrv: getStream(site, "videos/"+vodID, quality)
            GrpcSrv-->>CtxMgr: resolved URL
            
            CtxMgr->>VodDB: MarkVODStarted(vodID, user, site, title)
            CtxMgr->>FFmpeg: downloadVOD(user, vod, url, outLoc, moveLoc, vodDB)
            
            FFmpeg->>FileIO: Write video with stream-copy
            FFmpeg-->>CtxMgr: completion status
            
            alt Success
                CtxMgr->>VodDB: MarkVODCompleted(vodID)
                CtxMgr->>FileIO: Move to final destination
            else Failure
                CtxMgr->>VodDB: MarkVODFailed(vodID)
            end
        else VOD already downloaded or in-progress
            VodDB-->>CtxMgr: false (skip)
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Infrastructure, configuration, and core improvements #507: Overlaps in CI/workflow updates (.github/workflows), streaming client/server modifications (streamdl.go, download_stream.go), and process/IO handling for FFmpeg invocation and URL resolution.

Poem

🐰 Hop, hop! VOD dreams take flight,
SQLite tracks each download night,
gRPC whispers, FFmpeg sings,
VOD persistence—what joy it brings! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/twitch-vod-support

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[biodrone]

Duplicate — updating existing draft PR #551 instead.