StreamRecorder/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Go-based HLS (HTTP Live Streaming) downloader that monitors M3U8 playlists and downloads video segments in real-time. The program takes a master M3U8 playlist URL, parses all available stream variants (different qualities/bitrates), and continuously monitors each variant's chunklist for new segments to download.

Architecture

The project follows a modular architecture with clear separation of concerns:

• cmd/: Entry points for different execution modes
  • downloader/main.go: Main downloader application that orchestrates variant downloading
  • proc/main.go: Alternative processor entry point (currently minimal)
• pkg/: Core packages containing the application logic
  • media/: HLS streaming and download logic
    • stream.go: Stream variant parsing and downloading orchestration (GetAllVariants, VariantDownloader)
    • playlist.go: M3U8 playlist loading and parsing (LoadMediaPlaylist)
    • segment.go: Individual segment downloading logic (DownloadSegment, SegmentJob)
  • constants/constants.go: Configuration constants (URLs, timeouts, output paths)
  • httpClient/error.go: HTTP error handling utilities

Core Functionality

The main workflow is:

1. Parse Master Playlist: GetAllVariants() fetches and parses the master M3U8 to extract all stream variants with different qualities/bitrates
2. Concurrent Monitoring: Each variant gets its own goroutine running VariantDownloader() that continuously polls for playlist updates
3. Segment Detection: When new segments appear in a variant's playlist, they are queued for download
4. Parallel Downloads: Segments are downloaded concurrently with configurable worker pools and retry logic
5. Quality Organization: Downloaded segments are organized by resolution (1080p, 720p, etc.) in separate directories

Key Data Structures

• StreamVariant: Represents a stream quality variant with URL, bandwidth, resolution, and output directory
• SegmentJob: Represents a segment download task with URI, sequence number, and variant info

Common Development Commands

# Build the downloader application
go build -o stream-recorder ./cmd/downloader

# Run the downloader
go run ./cmd/downloader/main.go

# Run with module support
go mod tidy

# Test the project (when tests are added)
go test ./...

# Format code
go fmt ./...

Configuration

Key configuration is managed in pkg/constants/constants.go:

• MasterURL: The master M3U8 playlist URL to monitor
• WorkerCount: Number of concurrent segment downloaders per variant
• RefreshDelay: How often to check for playlist updates (3 seconds)
• OutputDirPath: Base directory for downloaded segments
• HTTP headers for requests (User-Agent, Referer)

Monitoring and Downloads

The application implements real-time stream monitoring:

• Continuous Polling: Each variant playlist is checked every 3 seconds for new segments
• Deduplication: Uses segment URIs and sequence numbers to avoid re-downloading
• Graceful Shutdown: Responds to SIGINT/SIGTERM signals for clean exit
• Error Resilience: Retries failed downloads and handles HTTP 403 errors specially
• Quality Detection: Automatically determines resolution from bandwidth or explicit resolution data

Error Handling

The implementation uses proper Go error handling patterns with custom HTTP error types. Failed downloads are logged with clear status indicators (✓ for success, ✗ for failure).