Metadata-Version: 2.4
Name: chzzk-archiver
Version: 0.2.0
License-Expression: Unlicense
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Dist: websockets>=12.0
Maintainer: Mina Her
Maintainer-email: Mina Her <minacle@live.com>
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# CHZZK Archiver

CLI for archiving CHZZK live streams and replay videos with chat.

It accepts live URLs, replay URLs, channel IDs, and video numbers, saves the original HLS capture locally, records chat as JSONL, and can remux the capture to MP4 with `ffmpeg`.

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)
- `ffmpeg` on `PATH` if you want `archive.mp4`

## Install

```bash
uv sync
```

## Quick start

```bash
# Inspect a live stream or replay and list available qualities
uv run chzzk-archiver probe https://chzzk.naver.com/live/<channel-id>
uv run chzzk-archiver probe https://chzzk.naver.com/video/<video-no>

# Record a live stream
uv run chzzk-archiver record https://chzzk.naver.com/live/<channel-id> --quality best

# Start recording at a local time (live only)
uv run chzzk-archiver record https://chzzk.naver.com/live/<channel-id> --start-at 22:00

# Record a replay
uv run chzzk-archiver record https://chzzk.naver.com/video/<video-no> --quality 1080p

# Remux an existing capture later
uv run chzzk-archiver remux archives/<session-dir> --overwrite
```

You can also pass identifiers directly:

```bash
uv run chzzk-archiver record <channel-id>
uv run chzzk-archiver record <video-no>
```

## Commands

| Command | Purpose |
| --- | --- |
| `probe <target>` | Show metadata and available qualities before recording. |
| `record <target>` | Archive video and chat into a new session directory. |
| `remux <archive-dir>` | Create `archive.mp4` from an existing `capture.m3u8`. |

## Useful options

- `--quality best|worst|1080p|720p|...`
- `--cookies <cookie-header-or-file>` for streams that require login
- `--no-chat` to skip chat recording
- `--no-remux` to skip MP4 creation
- `--start-at HH:MM` to wait for a local time before live recording
- `--mode hls|llhls|auto` and `--include-parts` for LL-HLS captures
- `--max-seconds <n>` to stop after a fixed duration
- `--log-level DEBUG` for detailed download logs

Example with cookies:

```bash
uv run chzzk-archiver --cookies cookies.txt record https://chzzk.naver.com/live/<channel-id>
```

## Output

Each `record` run creates a directory under `archives/` containing:

- `raw/`: downloaded init files and media segments
- `capture.m3u8`: local playlist pointing to `raw/`
- `archive.mp4`: remuxed MP4 when `ffmpeg` is available and remuxing is enabled
- `chat.jsonl`: recorded live or replay chat when available
- `metadata.json`: stream metadata and selected options

During `record`, progress logs go to stderr and the final result is printed as JSON to stdout.

## Behavior notes

- Live recording retries automatically until playable media is available.
- Press `Ctrl+C` during `record` to stop gracefully; remuxing is still attempted unless `--no-remux` is set.
- `--start-at` only works for live targets, not replay videos.

## Limitations and safety

- This project uses unofficial CHZZK endpoints, so API behavior may change.
- Use it only for streams or videos you are allowed to access.
- It does not bypass DRM, paywalls, region restrictions, or other access controls.
