chzzk-archiver 0.2.0__tar.gz

chzzk_archiver-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+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.

chzzk_archiver-0.2.0/README.md

@@ -0,0 +1,93 @@
+# 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.

chzzk_archiver-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "chzzk-archiver"
+version = "0.2.0"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "websockets>=12.0",
+]
+maintainers = [{ name = "Mina Her", email = "minacle@live.com" }]
+license = "Unlicense"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+chzzk-archiver = "chzzk_archiver:main"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"

chzzk_archiver-0.2.0/src/chzzk_archiver/__init__.py

@@ -0,0 +1,7 @@
+"""CHZZK live archiver."""
+
+from .cli import main
+
+__all__ = ["__version__", "main"]
+
+__version__ = "0.1.0"

chzzk_archiver-0.2.0/src/chzzk_archiver/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

chzzk_archiver-0.2.0/src/chzzk_archiver/chat.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Event
+from typing import Any
+
+from .http_client import HttpClient
+
+
+CHAT_ACCESS_TOKEN_URL = "https://comm-api.game.naver.com/nng_main/v1/chats/access-token"
+VIDEO_CHATS_URL = "https://api.chzzk.naver.com/service/v1/videos/{video_no}/chats"
+
+CMD_PING = 0
+CMD_PONG = 10000
+CMD_CONNECT = 100
+CMD_CONNECTED = 10100
+CMD_REQUEST_RECENT_CHAT = 5101
+CMD_RECENT_CHAT = 15101
+CMD_CHAT = 93101
+CMD_DONATION = 93102
+CMD_NOTICE = 94010
+CMD_BLIND = 94006
+
+
+class ChatError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class ChatAccess:
+    chat_channel_id: str
+    access_token: str
+    extra_token: str | None = None
+
+
+def chat_socket_url(chat_channel_id: str) -> str:
+    server_index = sum(ord(char) for char in chat_channel_id) % 9 + 1
+    return f"wss://kr-ss{server_index}.chat.naver.com/chat"
+
+
+def _parse_json_field(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError:
+        return value
+
+
+def normalize_chat_frame(raw: str) -> list[dict[str, Any]]:
+    try:
+        frame = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ChatError("Chat frame is not valid JSON") from exc
+
+    cmd = frame.get("cmd")
+    body = frame.get("bdy")
+    if cmd not in {CMD_CHAT, CMD_RECENT_CHAT, CMD_DONATION, CMD_NOTICE, CMD_BLIND}:
+        return []
+
+    if isinstance(body, dict) and isinstance(body.get("messageList"), list):
+        messages = body["messageList"]
+    elif isinstance(body, list):
+        messages = body
+    elif body:
+        messages = [body]
+    else:
+        messages = []
+
+    normalized: list[dict[str, Any]] = []
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        profile = _parse_json_field(message.get("profile")) or {}
+        extras = _parse_json_field(message.get("extras")) or {}
+        normalized.append(
+            {
+                "cmd": cmd,
+                "message": message.get("msg") or message.get("message") or message.get("content") or "",
+                "message_type": message.get("msgTypeCode") or message.get("messageTypeCode"),
+                "message_time": message.get("msgTime") or message.get("messageTime"),
+                "member_count": message.get("mbrCnt") or message.get("memberCount"),
+                "profile": profile,
+                "extras": extras,
+                "hidden": (message.get("msgStatusType") or message.get("messageStatusType")) == "HIDDEN",
+                "received_at": int(time.time() * 1000),
+            }
+        )
+    return normalized
+
+
+def normalize_replay_chat_message(message: dict[str, Any]) -> dict[str, Any]:
+    profile = _parse_json_field(message.get("profile")) or {}
+    extras = _parse_json_field(message.get("extras")) or {}
+    return {
+        "message": message.get("msg") or message.get("message") or message.get("content") or "",
+        "message_type": message.get("msgTypeCode") or message.get("messageTypeCode"),
+        "message_time": message.get("msgTime") or message.get("messageTime"),
+        "player_message_time": message.get("playerMessageTime"),
+        "member_count": message.get("mbrCnt") or message.get("memberCount"),
+        "profile": profile,
+        "extras": extras,
+        "hidden": (message.get("msgStatusType") or message.get("messageStatusType")) == "HIDDEN",
+        "received_at": int(time.time() * 1000),
+    }
+
+
+class ChatClient:
+    def __init__(self, http: HttpClient) -> None:
+        self.http = http
+
+    def fetch_access_token(self, chat_channel_id: str, chat_type: str = "STREAMING") -> ChatAccess:
+        query = urllib.parse.urlencode({"channelId": chat_channel_id, "chatType": chat_type})
+        payload = self.http.get_json(
+            f"{CHAT_ACCESS_TOKEN_URL}?{query}",
+            headers={
+                "Accept": "application/json, text/plain, */*",
+                "Origin": "https://chzzk.naver.com",
+                "Referer": "https://chzzk.naver.com/",
+            },
+        )
+        if not isinstance(payload, dict) or not isinstance(payload.get("content"), dict):
+            raise ChatError("Chat access-token response is not valid")
+        content = payload["content"]
+        access_token = content.get("accessToken")
+        if not isinstance(access_token, str) or not access_token:
+            raise ChatError("Chat access-token response does not contain an accessToken")
+        extra_token = content.get("extraToken") if isinstance(content.get("extraToken"), str) else None
+        return ChatAccess(chat_channel_id=chat_channel_id, access_token=access_token, extra_token=extra_token)
+
+    def fetch_video_chats(
+        self,
+        video_no: int,
+        *,
+        player_message_time: int = 1000,
+        previous_video_chat_size: int = 50,
+    ) -> dict[str, Any]:
+        query = urllib.parse.urlencode(
+            {
+                "playerMessageTime": player_message_time,
+                "previousVideoChatSize": previous_video_chat_size,
+            }
+        )
+        payload = self.http.get_json(
+            f"{VIDEO_CHATS_URL.format(video_no=video_no)}?{query}",
+            headers={
+                "Accept": "application/json, text/plain, */*",
+                "Origin": "https://chzzk.naver.com",
+                "Referer": f"https://chzzk.naver.com/video/{video_no}",
+            },
+        )
+        if not isinstance(payload, dict) or not isinstance(payload.get("content"), dict):
+            raise ChatError("Video chats response is not valid")
+        return payload["content"]
+
+    def write_video_chats(
+        self,
+        video_no: int,
+        output_path: Path,
+        *,
+        page_size: int = 50,
+        initial_player_message_time: int = 1000,
+    ) -> int:
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        player_message_time = initial_player_message_time
+        written = 0
+        seen: set[tuple[Any, Any, Any, Any]] = set()
+
+        with output_path.open("a", encoding="utf-8") as output:
+            while True:
+                content = self.fetch_video_chats(
+                    video_no,
+                    player_message_time=player_message_time,
+                    previous_video_chat_size=page_size,
+                )
+                rows: list[dict[str, Any]] = []
+                for key in ("previousVideoChats", "videoChats"):
+                    value = content.get(key)
+                    if isinstance(value, list):
+                        rows.extend(message for message in value if isinstance(message, dict))
+                for row in rows:
+                    normalized = normalize_replay_chat_message(row)
+                    dedupe_key = (
+                        normalized.get("message_time"),
+                        normalized.get("player_message_time"),
+                        row.get("userIdHash"),
+                        normalized.get("message"),
+                    )
+                    if dedupe_key in seen:
+                        continue
+                    seen.add(dedupe_key)
+                    output.write(json.dumps(normalized, ensure_ascii=False, sort_keys=True) + "\n")
+                    written += 1
+
+                next_player_message_time = content.get("nextPlayerMessageTime")
+                if not rows or not isinstance(next_player_message_time, int) or next_player_message_time <= player_message_time:
+                    break
+                player_message_time = next_player_message_time
+
+        return written
+
+
+class ChatWebSocketRecorder:
+    def __init__(self, access: ChatAccess, output_path: Path, *, recent_count: int = 50) -> None:
+        self.access = access
+        self.output_path = output_path
+        self.recent_count = recent_count
+
+    async def record_until_stopped(self, stop_event: Event) -> None:
+        try:
+            import websockets
+        except ImportError as exc:
+            raise ChatError("The websockets package is required for chat recording") from exc
+
+        self.output_path.parent.mkdir(parents=True, exist_ok=True)
+        async with websockets.connect(chat_socket_url(self.access.chat_channel_id), ping_interval=None) as socket:
+            await socket.send(
+                json.dumps(
+                    {
+                        "ver": "2",
+                        "cmd": CMD_CONNECT,
+                        "svcid": "game",
+                        "cid": self.access.chat_channel_id,
+                        "tid": 1,
+                        "bdy": {
+                            "uid": None,
+                            "devType": 2001,
+                            "accTkn": self.access.access_token,
+                            "accessToken": self.access.access_token,
+                            "auth": "READ",
+                        },
+                    },
+                    ensure_ascii=False,
+                )
+            )
+
+            sid: str | None = None
+            with self.output_path.open("a", encoding="utf-8") as output:
+                while not stop_event.is_set():
+                    try:
+                        raw = await asyncio.wait_for(socket.recv(), timeout=1.0)
+                    except asyncio.TimeoutError:
+                        continue
+                    if not isinstance(raw, str):
+                        continue
+                    frame = json.loads(raw)
+                    cmd = frame.get("cmd")
+                    if cmd == CMD_PING:
+                        await socket.send(json.dumps({"ver": "2", "cmd": CMD_PONG}))
+                        continue
+                    if cmd == CMD_CONNECTED:
+                        sid = (frame.get("bdy") or {}).get("sid")
+                        if sid:
+                            await socket.send(
+                                json.dumps(
+                                    {
+                                        "ver": "2",
+                                        "cmd": CMD_REQUEST_RECENT_CHAT,
+                                        "svcid": "game",
+                                        "cid": self.access.chat_channel_id,
+                                        "sid": sid,
+                                        "tid": 2,
+                                        "bdy": {"recentMessageCount": self.recent_count},
+                                    },
+                                    ensure_ascii=False,
+                                )
+                            )
+                        continue
+                    for message in normalize_chat_frame(raw):
+                        output.write(json.dumps(message, ensure_ascii=False, sort_keys=True) + "\n")
+                        output.flush()