# 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).