@zfadhli/tokrec 0.13.0 → 0.15.2

package/README.md

@@ -1,430 +1,126 @@
-<div align="center">
+# @zfadhli/tokrec
 
-# tokrec
+Library half of [tokrec](https://github.com/zfadhli/tokrec) — polls a TikTok user's live status, records the stream while it is live, and returns playable MP4 files.
 
-**Minimal TikTok live stream recorder — Bun + TypeScript**
-
-[![CI Status](https://img.shields.io/github/actions/workflow/status/zfadhli/tokrec/ci.yml?style=flat-square&label=CI)](https://github.com/zfadhli/tokrec/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@zfadhli/tokrec?style=flat-square)](https://www.npmjs.com/package/@zfadhli/tokrec)
-[![npm downloads](https://img.shields.io/npm/dw/@zfadhli/tokrec?style=flat-square)](https://www.npmjs.com/package/@zfadhli/tokrec)
-[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.2-14151a?style=flat-square&logo=bun)](https://bun.sh)
-[![License](https://img.shields.io/npm/l/@zfadhli/tokrec?style=flat-square)](LICENSE)
-
-[Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [CLI options](#cli-options) · [Background recording](#background-recording-tmux) · [Authentication](#authentication) · [How it works](#how-it-works) · [Library API](#library-api) · [FAQ](#faq)
-
-</div>
-
-`tokrec` polls a TikTok user's live status, detects when they go live, downloads the stream, and post-processes it with FFmpeg into playable MP4 segments. Available as both a CLI tool and a TypeScript library.
-
-> [!NOTE]
-> This is **not** an all-in-one TikTok downloader. It focuses on **live stream recording** with automatic reconnection, graceful shutdown, and clean terminal output. For downloading uploaded videos, see other tools.
-
----
-
-## Features
-
-- **Automatic polling** — checks every N minutes (default 3) and starts recording as soon as the user goes live
-- **Stream reconnection** — TikTok stream segments are short-lived (30-60s). When one ends, `tokrec` transparently fetches a fresh URL and continues writing to the same file
-- **Duration-limited recording** — record for a fixed time (`-d`) and auto-exit, or record indefinitely (default)
-- **Time-aligned MP4 segments** — post-recording, optionally split the stream into configurable-length MP4 segments, each independently playable
-- **Audio normalization** — EBU R128 two-pass loudness normalization via [peaknorm](https://github.com/zfadhli/peaknorm)
-- **Graceful shutdown** — responds to `SIGINT`/`SIGTERM`/`SIGHUP`. Aborts the download, flushes buffered data, converts to MP4, and exits cleanly
-- **Firefox cookie auto-detection** — reads `sessionid_ss` from Firefox's SQLite cookie store automatically (no config file needed)
-- **Live progress display** — animated spinner with real-time byte count, elapsed time, and download speed
-- **Typed event system** — 15 events with typed payloads for lifecycle tracking
-- **Proxy support** — route traffic through an HTTP proxy for regional access
-- **FLV + HLS support** — automatically detects and handles both stream formats
-- **Background recording** — tmux integration keeps recordings alive after terminal close, with per-user session management
-- **Multi-user** — record multiple users simultaneously, each in its own tmux session
-- **71+ passing tests** — unit tests with real TikTok HTML/API fixtures
-
----
-
-## Requirements
-
-- **FFmpeg** — must be on your `$PATH` for MP4 conversion and segmenting
-  - Linux: `apt install ffmpeg`
-  - macOS: `brew install ffmpeg`
-  - Windows: `choco install ffmpeg`
-- **Bun** (optional, for development) — Node.js 20+ can run the built package
-
----
-
-## Installation
-
-### CLI tool (global)
-
-```bash
-npm install -g @zfadhli/tokrec
-```
-
-Then run:
+[![CI](https://img.shields.io/github/actions/workflow/status/zfadhli/tokrec/ci.yml?style=flat-square&label=CI)](https://github.com/zfadhli/tokrec/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@zfadhli/tokrec?style=flat-square)](https://github.com/zfadhli/tokrec/blob/main/LICENSE)
 
-```bash
-tokrec -u username
-```
+Want the ready-made command-line recorder instead? Use
+[`@zfadhli/tokrec-cli`](https://www.npmjs.com/package/@zfadhli/tokrec-cli).
 
-### One-off use (npx)
-
-```bash
-npx @zfadhli/tokrec -u username
-```
-
-### As a library
+## Install
 
 ```bash
+bun add @zfadhli/tokrec
+# or
 npm install @zfadhli/tokrec
 ```
 
-```ts
-import { createRecorder } from "@zfadhli/tokrec";
-
-const recorder = createRecorder({ user: "username" });
-recorder.on("recording:end", (info) => console.log("Done:", info.file));
-await recorder.start();
-```
-
-> [!TIP]
-> When using as a library, logs print to the console by default. To suppress console output (e.g., if you run your own UI), set `logConsole: false` in the config.
-
----
+Built for Bun ≥ 1.2. Nothing in the library is Bun-only — `Bun.which()` is used
+when it exists and falls back to a `PATH` search — so the published `dist/`
+also runs under Node ≥ 20. **FFmpeg must be on `PATH`** for MP4 conversion,
+segmenting, and normalization.
 
 ## Quick start
 
-```bash
-# Record a live stream (Ctrl+C to stop)
-tokrec -u username
-
-# Record for 10 minutes, then exit
-tokrec -u username -d 10
-
-# Record for 10 minutes, split into 5-minute segments
-tokrec -u username -d 10 -s 5
-
-# Use a proxy and custom output directory
-tokrec -u username -o ./videos -p http://127.0.0.1:8080
-
-# Enable audio normalization
-tokrec -u username --normalize
-```
-
-### Background recording (tmux)
-
-```bash
-# Start in background — survives terminal close
-tokrec start -u username
-
-# Record multiple users simultaneously
-tokrec start -u user1
-tokrec start -u user2
-
-# Check active sessions
-tokrec status
-
-# Reattach to see live output
-tmux attach -t tokrec-user1
-
-# Detach without killing (Ctrl+B, D)
-
-# Stop a specific user
-tokrec stop -u user1
-
-# Stop all sessions
-tokrec stop
-```
-
-> [!TIP]
-> Both `-d` and `-s` accept values in **minutes** (the tool converts them internally).
-
----
-
-## CLI options
-
-| Option                        | Shorthand | Default          | Description                                                                                |
-| ----------------------------- | --------- | ---------------- | ------------------------------------------------------------------------------------------ |
-| `--user <name>`               | `-u`      | _(required)_     | TikTok username (with or without `@`)                                                      |
-| `--output <dir>`              | `-o`      | `./recordings`   | Output directory                                                                           |
-| `--interval <minutes>`        | `-i`      | `3`              | Polling interval (min 1)                                                                   |
-| `--duration <minutes>`        | `-d`      | unlimited        | Max recording duration. Implies one-shot (exit after recording)                            |
-| `--segment-minutes <minutes>` | `-s`      | disabled         | Split recording into MP4 segments of this length                                           |
-| `--proxy <url>`               | `-p`      | none             | HTTP proxy URL                                                                             |
-| `--cookies <path>`            | `-c`      | `./cookies.json` | Path to cookies JSON file                                                                  |
-| `--log-level <level>`         | `-l`      | `info`           | One of: `debug`, `info`, `warn`, `error`                                                   |
-| `--normalize`                 | _(none)_  | on               | Enable EBU R128 audio normalization (enabled by default, pass `--no-normalize` to disable) |
-| `--normalize-loudness <num>`  | _(none)_  | `-14`            | Target loudness in LUFS                                                                    |
-| `--normalize-codec <name>`    | _(none)_  | `libopus`        | Audio codec for normalized output (peaknorm default)                                       |
-| `--normalize-bitrate <str>`   | _(none)_  | `96k`            | Audio bitrate for normalized output (peaknorm default)                                     |
-| `--rate <n>`                  | _(none)_  | `5`              | Max API requests/sec (0 = unlimited). Prevents WAF triggering                              |
-| `--debug`                     | _(none)_  | off              | Show API debug logging on stderr                                                           |
-
-### Subcommands
-
-| Command  | Description                              | Example                                     |
-| -------- | ---------------------------------------- | ------------------------------------------- |
-| `start`  | Start recorder in a tmux session         | `tokrec start -u username`                  |
-| `stop`   | Stop tmux session(s)                     | `tokrec stop -u username` (or `tokrec stop` to stop all) |
-| `status` | Show active tmux sessions                | `tokrec status`                             |
-| `setup`  | Check cookie status or create cookies.json | `tokrec setup`                            |
-
----
-
-## Authentication
-
-TikTok's Slardar WAF blocks unauthenticated requests. You must provide a valid `sessionid_ss` cookie to bypass it.
-
-### Quick setup
-
-```bash
-tokrec setup
-```
-
-This checks for Firefox cookies (auto-detected) or `cookies.json`. If neither is found, it prompts you to enter your cookie value interactively.
-
-### Option 1: Firefox (auto-detected)
-
-If you're logged into TikTok in Firefox, `tokrec` automatically reads the cookie from Firefox's SQLite store. No config file needed.
-
-```bash
-tokrec -u username
-```
-
-You will see:
-
-```
-tokrec v0.11.0
-ℹ Firefox cookies loaded (30 cookies)
-```
-
-### Option 2: cookies.json
-
-1. Open TikTok in any browser and log in.
-2. Open DevTools → **Application** → **Cookies** → `www.tiktok.com`.
-3. Copy the value of `sessionid_ss` and create a `cookies.json` file:
-
-```json
-{
-  "sessionid_ss": "6c74daa215a8f34eeddf5162ca091668"
-}
-```
-
-You can also include the `tt-target-idc` cookie (optional, for regional routing):
-
-```json
-{
-  "sessionid_ss": "6c74daa215a8f34eeddf5162ca091668",
-  "tt-target-idc": "useast2a"
-}
-```
-
-4. Place `cookies.json` in the working directory (auto-detected) or pass `--cookies ./path/to/cookies.json`.
-
-> [!CAUTION]
-> Without valid cookies, the tool will report every user as **offline** because the WAF challenge page won't contain live-stream JSON data.
-
----
-
-## How it works
-
-### Detection flow
-
-```
-fetchLiveInfo(user)
-  ├─ tryFetchPage (www.tiktok.com → m.tiktok.com)
-  │    └─ WAF blocks both → API fallback
-  ├─ /api-live/user/room/ (bypasses WAF)
-  │    └─ Returns roomId + status (2=live, 4=offline)
-  └─ If live → /webcast/room/info/ for stream URL
-
-isRoomAlive(roomId)  [during recording]
-  ├─ Cache hit → return cached.isLive
-  └─ Cache miss → /webcast/room/check_alive/ → boolean (~100 bytes)
-
-getNextUrl()  [during recording]
-  ├─ isRoomAlive(roomId) → if dead, stop
-  ├─ Invalidate cache
-  └─ getLiveUrl(roomId) → fresh stream URL
-```
-
-### Pipeline
-
-```
-┌────────────┐   ┌──────────────┐   ┌──────────────┐   ┌─────────────────┐
-│  Poll tick  │ → │  Detect live │ → │  Download TS  │ → │  FFmpeg post    │
-│  (every Nm) │   │  3-tier      │   │  (auto-reconn.)│   │  (convert/      │
-│             │   │  fallback    │   │               │   │   segment)       │
-└────────────┘   └──────────────┘   └──────────────┘   └─────────────────┘
-```
-
-1. **Poll tick** — every N minutes, the monitor calls the check function.
-2. **Live detection** — uses a three-tier fallback:
-   - Fast-path from `SIGI_STATE` on the `/live` page (~95% of cases)
-   - Brute-force recursive search of the entire JSON (survives key name changes)
-   - Webcast API fallback (`/webcast/room/info/`)
-3. **Download** — the stream is downloaded via FFmpeg stdout pipe to a `.ts` file. TikTok's short-lived URLs are handled transparently: when a URL expires, `getNextUrl()` fetches a fresh one. Duration limit is enforced **inside** FFmpeg via the `-t` flag for precise cutoff.
-4. **Post-processing** — the `.ts` file is remuxed to MP4 via `ffmpeg -c copy` (no re-encode, fast). If segmenting is enabled, FFmpeg's segment muxer splits into `_partN.mp4` files. Audio normalization runs last if enabled.
-
-### Output structure
-
-```
-./recordings/
-  username=20260614_143000.ts               # raw download (deleted after conversion)
-  username=20260614_143000.mp4              # remuxed MP4 (no segmenting)
-  username=20260614_143000_part1.mp4        # segment 1 (with -s)
-  username=20260614_143000_part2.mp4        # segment 2
-  ...
-```
-
-File naming: `{username}={YYYYMMDD}_{HHMMSS}[_partN].mp4`
-
-### Event system
-
-The recorder emits typed events that you can subscribe to via `recorder.on()`:
-
-| Event                | Payload                     | When                              |
-| -------------------- | --------------------------- | --------------------------------- |
-| `checking`           | `{ user }`                  | Before each poll tick             |
-| `tick`               | `{ user, isLive, roomId? }` | After checking live status        |
-| `recording:start`    | `{ user, file }`            | When recording begins             |
-| `download:progress`  | `{ bytes, elapsed, speed }` | During download (~1s intervals)   |
-| `download:end`       | `{ file, duration, size }`  | When download completes           |
-| `recording:end`      | `{ file, duration, size }`  | Per segment/file after conversion |
-| `segmenting:start`   | `{ input, outputPattern }`  | Before FFmpeg segmenting          |
-| `segmenting:end`     | `{ segments }`              | After segmenting                  |
-| `converting:start`   | `{ input }`                 | Before simple conversion          |
-| `converted`          | `{ input, output }`         | After each converted file         |
-| `normalize:start`    | `{ file }`                  | Before audio normalization        |
-| `normalize:progress` | `{ file, percent, phase }`  | During normalization              |
-| `normalize:end`      | `{ input, output }`         | After normalization               |
-| `normalize:error`    | `{ input, error }`          | On normalization error            |
-| `error`              | `err: TikTokError`          | On non-fatal errors               |
-
----
-
-## Library API
-
-### `createRecorder(config)`
-
 ```ts
-import { createRecorder } from "@zfadhli/tokrec";
-import type { RecorderConfig, RecorderController, RecorderEvent } from "@zfadhli/tokrec";
-
-const recorder: RecorderController = createRecorder({
-  user: "username", // required
-  outputDir: "./videos", // default: './recordings'
-  interval: 3, // polling interval in minutes
-  duration: 600, // max recording duration in seconds
-  segmentMinutes: 20, // segment length in minutes
-  proxy: "http://127.0.0.1:8080",
-  cookies: { sessionid_ss: "..." },
-  logLevel: "info",
-  logConsole: true,
-});
-```
-
-### `RecorderController`
+import { createRecorder } from "@zfadhli/tokrec"
+
+const recorder = createRecorder({
+  user: "somebody",
+  outputDir: "./recordings",
+  interval: 3, // minutes between live-status polls
+})
+
+recorder.on("verdict", (v) => console.log("status:", v.reason))
+recorder.on("progress", (p) => {
+  if (p.kind === "download") console.log(`${p.percent.toFixed(1)}%`)
+})
+recorder.on("record", (e) => {
+  if (e.phase === "end") console.log("saved:", e.file)
+})
+recorder.on("failure", (err) => console.error(err.code, err.message))
+
+await recorder.start() // polls until offline or stop()
+```
+
+`start()` resolves when the run ends; call `stop()` from a signal handler to shut
+down gracefully — the download is aborted, buffered data is flushed, and the
+partial recording is still remuxed to `.mp4` before the promise settles.
+
+## Configuration
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `user` | `string` | — | TikTok username (required) |
+| `outputDir` | `string` | `./recordings` | Destination directory |
+| `interval` | `number` | `3` | Minutes between live-status polls |
+| `duration` | `number` | `0` (unlimited) | Max recording length in **seconds** |
+| `proxy` | `string` | — | HTTP proxy, e.g. `http://127.0.0.1:8080` |
+| `cookiesPath` | `string` | `./cookies.json` | Path to a cookies file |
+| `cookies` | `CookieAuth` | — | Cookie auth passed as an object instead of a file |
+| `logLevel` | `"debug" \| "info" \| "warn" \| "error"` | `info` | Console verbosity |
+| `logConsole` | `boolean` | `true` | Set `false` when you render your own output |
+| `segmentMinutes` | `number` | `0` (off) | Split the recording into N-minute segments |
+| `normalizeAudio` | `boolean` | `false` | EBU R128 loudness normalization via [peaknorm](https://github.com/zfadhli/peaknorm) |
+| `normalizeLoudness` | `number` | `-14` | Target loudness in LUFS |
+| `normalizeCodec` | `string` | `libopus` | Audio codec for normalized output |
+| `normalizeBitrate` | `string` | `96k` | Audio bitrate for normalized output |
+| `ratePerSecond` | `number` | `5` | Request cap; `0` disables the limiter |
+| `debug` | `boolean` | `false` | API debug logging on stderr |
+
+> The CLI accepts `--duration` in minutes; the library takes seconds.
+
+## Events
+
+Four typed channels:
+
+| Event | Payload | Fires when |
+| --- | --- | --- |
+| `verdict` | `Verdict` — `reason`, `stream`, `evidence` | Every status poll resolves |
+| `record` | `RecordEvent` | Recording lifecycle: `start`, `download`, `segment`, `convert`, `normalize`, `end` |
+| `progress` | `ProgressEvent` — `{ kind: "download" }` or `{ kind: "normalize" }` | Bytes/percent updates |
+| `failure` | `TikTokError` | A recoverable or fatal error |
+
+`Verdict["reason"]` is one of `live`, `offline`, `restricted`, `no-stream-url`,
+`no-room-id`, `error`, and carries the evidence sources that produced it.
+
+## Controller
 
 ```ts
 interface RecorderController {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  getStatus(): RecorderStatus;
-  on<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void;
-  off<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void;
+  start(): Promise<void>
+  stop(): Promise<void> // graceful: joins the active recording first
+  getStatus(): RecorderStatus
+  on(event, handler): void
+  off(event, handler): void
 }
 ```
 
-### `RecorderStatus`
+`RecorderStatus` exposes `state`, `user`, `currentFile`, `sessionDuration`,
+`lastPollTime`, and `lastError`.
 
-```ts
-interface RecorderStatus {
-  state: "idle" | "polling" | "recording" | "converting" | "stopped";
-  user: string;
-  currentFile?: string;
-  sessionDuration?: number;
-  lastPollTime?: string;
-  lastError?: string;
-}
-```
-
-### Example: build a notification bot
-
-```ts
-import { createRecorder } from "@zfadhli/tokrec";
-
-const recorder = createRecorder({ user: "username" });
-
-recorder.on("checking", ({ user }) => console.log(`Checking @${user}...`));
-recorder.on("tick", ({ isLive, roomId, user }) => {
-  if (isLive) {
-    console.log(`@${user} is LIVE! (room: ${roomId})`);
-    // Send a Discord/Telegram notification here
-  }
-});
-recorder.on("recording:end", ({ file, duration }) => {
-  console.log(`Recorded ${file} (${Math.round(duration)}s)`);
-});
-recorder.on("error", (err) => console.error(`[${err.kind}] ${err.message}`));
-
-await recorder.start();
-```
+## Exports
 
----
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `createRecorder(config)` | value | Build a `RecorderController` |
+| `TikTokError` | value | Typed error class |
+| `isLiveReason(reason)` | value | Narrow a verdict reason |
+| `bytesToHuman`, `formatDuration`, `relativeTime`, `sanitizeUser` | value | Formatting helpers used by the CLI |
+| `RecorderConfig`, `RecorderController`, `RecorderStatus`, `RecorderEvent`, `RecorderEventHandler`, `RecordEvent`, `ProgressEvent`, `RecordedFile`, `LiveReason`, `Verdict`, `Evidence`, `EvidenceOutcome`, `RoomRef`, `StreamRef`, `SourceId`, `Phase`, `LogLevel`, `TikTokErrorCode` | type | Public types (18) |
 
-## FAQ
-
-### Why does the tool say "offline" for every user?
-
-You likely don't have a valid `sessionid_ss` cookie. See the [Authentication](#authentication) section.
-
-### Why does the download stop after 30 seconds?
-
-TikTok serves live streams as short FLV segments (~30-60s). `tokrec` handles reconnection transparently — this is expected behavior and the download continues with a fresh URL.
-
-### Can I record multiple users at once?
-
-Yes. Use tmux background sessions:
-
-```bash
-tokrec start -u user1
-tokrec start -u user2
-tokrec status   # shows all active sessions
-```
-
-Each user gets an independent tmux session (`tokrec-{user}`), so they run in parallel without interfering.
-
-### Can I use this with Node.js instead of Bun?
-
-Yes. The package is built to ESM for Node.js 20+. Bun is optional for development.
-
-### Where are the log files?
-
-`tiktok-recorder.log` in the working directory, with rotating backups. Console output is also available via `--log-level`.
-
-### Does it work if the user goes live while I'm not running it?
-
-No. `tokrec` only polls while it's running. Use tmux background sessions for always-on monitoring:
-
-```bash
-tokrec start -u username   # runs in tmux, survives terminal close
-tmux attach -t tokrec-username   # reattach to view output
-```
-
----
-
-## Troubleshooting
-
-### FFmpeg not found
-
-Install FFmpeg and ensure it is on your `$PATH`:
-
-```bash
-which ffmpeg    # should print a path
-```
+Error codes: `config-error`, `ffmpeg-not-found`, `ffmpeg-error`, `aborted`,
+`unknown`.
 
-### "WAF blocked" errors
+## Output
 
-Your `sessionid_ss` cookie has expired or is invalid. Generate a fresh one from your browser's DevTools.
+Recordings are named `<user>=YYYYMMDD_HHMMSS.mp4`; segmenting produces
+`<name>_partN.mp4`.
 
-### The process doesn't exit after a `-d` recording
+## Links
 
-Make sure you're using v0.7.1 or later. Earlier versions continued polling instead of exiting.
+- [CLI package](https://www.npmjs.com/package/@zfadhli/tokrec-cli)
+- [Repository](https://github.com/zfadhli/tokrec) · [Changelog](https://github.com/zfadhli/tokrec/blob/main/CHANGELOG.md)
+- [MIT License](https://github.com/zfadhli/tokrec/blob/main/LICENSE)

package/dist/app/abort.mjs

@@ -0,0 +1,14 @@
+//#region src/app/abort.ts
+function abortScope(parent) {
+	const controller = new AbortController();
+	if (parent) if (parent.aborted) controller.abort(parent.reason);
+	else parent.addEventListener("abort", () => controller.abort(parent.reason), { once: true });
+	return {
+		signal: controller.signal,
+		close: (reason) => controller.abort(reason)
+	};
+}
+//#endregion
+export { abortScope };
+
+//# sourceMappingURL=abort.mjs.map

package/dist/app/abort.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.mjs","names":[],"sources":["../../src/app/abort.ts"],"sourcesContent":["/**\n * One cancellation scope per recorder run. Everything that can block accepts\n * `scope.signal`; `close()` aborts in-flight work immediately.\n */\n\nexport interface AbortScope {\n  readonly signal: AbortSignal\n  close(reason?: string): void\n}\n\nexport function abortScope(parent?: AbortSignal): AbortScope {\n  const controller = new AbortController()\n  if (parent) {\n    if (parent.aborted) controller.abort(parent.reason)\n    else parent.addEventListener(\"abort\", () => controller.abort(parent.reason), { once: true })\n  }\n  return { signal: controller.signal, close: (reason) => controller.abort(reason) }\n}\n"],"mappings":";AAUA,SAAgB,WAAW,QAAkC;CAC3D,MAAM,aAAa,IAAI,gBAAgB;CACvC,IAAI,QACF,IAAI,OAAO,SAAS,WAAW,MAAM,OAAO,MAAM;MAC7C,OAAO,iBAAiB,eAAe,WAAW,MAAM,OAAO,MAAM,GAAG,EAAE,MAAM,KAAK,CAAC;CAE7F,OAAO;EAAE,QAAQ,WAAW;EAAQ,QAAQ,WAAW,WAAW,MAAM,MAAM;CAAE;AAClF"}