77 lines
3.6 KiB
Markdown
77 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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). |