@zfadhli/tokrec 0.13.0 → 0.15.2

package/src/app/recorder.ts

@@ -0,0 +1,288 @@
+/**
+ * Recorder orchestrator — wires the TikTok client, stream download, and
+ * RecordingJob into a single RecorderController.
+ *
+ * Policy lives in `policy/tick.ts`; this file maps a TickPlan to effects and
+ * owns the session state those effects mutate. Everything a tick needs is
+ * constructed as a `const` in `start()` and passed in, so no call site has to
+ * assert a non-null module-level `let` back into existence.
+ */
+
+import { planTick, type TickFacts } from "../core/plan"
+import { verdictOf } from "../core/verdict"
+import { createHttpClient, type HttpClient } from "../io/http"
+import { type Converter, createConverter } from "../io/media/convert"
+import { downloadStream } from "../io/media/download"
+import { type AudioNormalizer, createAudioNormalizer } from "../io/media/normalize"
+import { createTikTokClient, type TikTokClient } from "../io/tiktok/client"
+import { type AbortScope, abortScope } from "./abort"
+import type { RecorderConfig, RecorderController, RecorderStatus } from "./config"
+import { resolveConfig } from "./config"
+import { createEventEmitter } from "./events"
+import { createRecordingJob, type RecordingJob } from "./job"
+import { createLogger } from "./logger"
+import { createPollingMonitor, type PollingMonitor } from "./loop"
+
+/** Max wait for a stop-time remux before aborting it (matches the pre-#32 cap). */
+const POST_REMUX_GRACE_MS = 10 * 60 * 1000
+
+/** Everything one poll tick needs, built by `start()` before the tick can run. */
+interface TickDeps {
+  client: TikTokClient
+  monitor: PollingMonitor
+  scope: AbortScope
+  post: AbortScope
+  converter: Converter
+  audioNormalizer: AudioNormalizer | null
+}
+
+/** What `stop()` has to join and release. */
+interface Running {
+  monitor: PollingMonitor
+  http: HttpClient
+  scope: AbortScope
+}
+
+export function createRecorder(config: RecorderConfig): RecorderController {
+  const cfg = resolveConfig(config)
+  const logger = createLogger({
+    level: cfg.logLevel,
+    logFile: "tiktok-recorder.log",
+    console: cfg.logConsole,
+  })
+
+  const emitter = createEventEmitter()
+
+  // Session state — written by ticks and by the job lifecycle, read by getStatus().
+  const status: RecorderStatus = { state: "idle", user: cfg.user }
+  let running: Running | null = null
+  let postScope: AbortScope | null = null
+  let currentJob: RecordingJob | null = null
+  let recordedSec = 0
+  let consecutiveErrors = 0
+
+  function setState(partial: Partial<RecorderStatus>): void {
+    const prev = status.state
+    Object.assign(status, partial)
+    if (partial.state !== undefined && partial.state !== prev) {
+      logger.info(`State: ${prev} → ${partial.state}`)
+      if (partial.state === "polling") status.lastPollTime = new Date().toISOString()
+    }
+  }
+
+  async function tick(d: TickDeps): Promise<void> {
+    const { client, monitor, scope, post } = d
+    if (scope.signal.aborted) return
+    const user = cfg.user
+
+    client.invalidateCache()
+    logger.info(`Checking @${user}...`)
+
+    const verdict = await client.getVerdict(user)
+    const facts: TickFacts = {
+      recording: currentJob !== null,
+      recordedSec,
+      oneShot: cfg.duration > 0,
+      consecutiveErrors,
+    }
+    consecutiveErrors =
+      verdict.reason === "error" || verdict.reason === "no-room-id" ? consecutiveErrors + 1 : 0
+
+    emitter.emit("verdict", verdict)
+    const plan = planTick(verdict, facts)
+
+    switch (plan.kind) {
+      case "poll": {
+        logger.info(
+          `@${user} ${plan.note} (reason: ${verdict.reason}, source: ${lastSource(verdict)})`,
+        )
+        return
+      }
+      case "hold": {
+        if (plan.reason === "restricted") {
+          logger.warn(
+            `@${user} is live but age-protected/restricted — stream unavailable (reason: restricted, status_code 4003110, room: ${plan.room.id})`,
+          )
+        } else {
+          logger.warn(
+            `@${user} is live but no stream URL found (reason: no-stream-url, room: ${plan.room.id})`,
+          )
+        }
+        return
+      }
+      case "stop": {
+        if (plan.why === "one-shot") {
+          logger.info("Duration limit reached — exiting")
+          monitor.stopAfterCurrentTick()
+        } else if (plan.why === "gave-up") {
+          logger.error(`@${user} gave up after ${consecutiveErrors} consecutive errors`)
+          monitor.stopAfterCurrentTick()
+        }
+        return
+      }
+      case "record": {
+        const { room, stream } = plan
+        logger.info(`@${user} is LIVE! (room: ${room.id}, reason: live)`)
+        setState({ state: "recording" })
+        emitter.emit("record", { phase: "start", user, file: "" })
+
+        const getNextUrl = async (): Promise<string | null> => {
+          if (scope.signal.aborted) return null
+          // Use the lightweight check_alive endpoint first — avoids a full
+          // page re-scan + room/info call when the stream is still active.
+          const alive = await client.isRoomAlive(room.id)
+          if (!alive) {
+            logger.info(`@${user} is no longer live — stopping`)
+            return null
+          }
+          client.invalidateCache()
+          return client.getLiveUrl(room.id)
+        }
+
+        const result = await downloadStream(
+          stream.url,
+          user,
+          cfg.outputDir,
+          cfg.duration,
+          (info) => emitter.emit("progress", { kind: "download", ...info }),
+          getNextUrl,
+          scope.signal,
+          logger,
+          cfg.cookies,
+        )
+
+        emitter.emit("record", { phase: "download", ...result })
+        recordedSec += result.duration
+
+        const job = createRecordingJob({
+          result,
+          cfg: { segmentMinutes: cfg.segmentMinutes },
+          logger,
+          converter: d.converter,
+          audioNormalizer: d.audioNormalizer,
+          signal: post.signal,
+          emitRecord: (event) => emitter.emit("record", event),
+          emitProgress: (event) => emitter.emit("progress", event),
+          emitFailure: (err) => emitter.emit("failure", err),
+          setState,
+        })
+        currentJob = job
+        try {
+          await job.finish()
+        } finally {
+          currentJob = null
+        }
+
+        // One-shot mode: if a duration was set, stop after this recording
+        if (cfg.duration > 0) {
+          logger.info("Duration limit reached — exiting")
+          monitor.stopAfterCurrentTick()
+        } else if (!scope.signal.aborted) {
+          // Recording ended because the stream went offline (not user-initiated
+          // stop). Immediately re-check via the lightweight endpoint.
+          const alive = await client.isRoomAlive(room.id)
+          if (!alive) {
+            logger.info(`@${user} is offline`)
+            emitter.emit(
+              "verdict",
+              verdictOf({ room: { ...room, live: false }, evidence: verdict.evidence }),
+            )
+          }
+        }
+        return
+      }
+    }
+  }
+
+  async function start(): Promise<void> {
+    if (status.state !== "idle") {
+      logger.warn(`start() ignored: already in state ${status.state}`)
+      return
+    }
+    const scope = abortScope()
+    // Post-processing outlives a user stop: Ctrl+C aborts the download, but the
+    // partial .ts is still remuxed to .mp4 before the process exits.
+    const post = abortScope()
+    postScope = post
+    currentJob = null
+    recordedSec = 0
+    consecutiveErrors = 0
+
+    logger.info(`Starting recorder for @${cfg.user}`)
+    const http = await createHttpClient(cfg)
+    const client = createTikTokClient(http, logger, cfg.debug, scope.signal)
+    const converter = createConverter(logger, post.signal)
+    const audioNormalizer = cfg.normalizeAudio
+      ? createAudioNormalizer(
+          {
+            loudness: cfg.normalizeLoudness,
+            audioCodec: cfg.normalizeCodec,
+            audioBitrate: cfg.normalizeBitrate,
+            onProgress: (file, percent, phase) =>
+              emitter.emit("progress", {
+                kind: "normalize",
+                file,
+                percent,
+                phase: phase as "analyzing" | "normalizing",
+              }),
+          },
+          logger,
+        )
+      : null
+
+    // Self-reference inside `onTick` is safe: the monitor calls it from
+    // `start()`, never during construction.
+    let monitor: PollingMonitor
+    monitor = createPollingMonitor({
+      intervalMinutes: cfg.interval,
+      signal: scope.signal,
+      logger,
+      onTick: () => tick({ client, monitor, scope, post, converter, audioNormalizer }),
+    })
+    running = { monitor, http, scope }
+
+    setState({ state: "polling" })
+    await monitor.start()
+  }
+
+  async function stop(): Promise<void> {
+    if (status.state === "stopped") {
+      logger.warn(`stop() ignored: already stopped`)
+      return
+    }
+    logger.info("Stopping recorder...")
+    running?.scope.close("user")
+
+    const grace = setTimeout(() => postScope?.close("stop-timeout"), POST_REMUX_GRACE_MS)
+    try {
+      const job = currentJob
+      if (job) {
+        logger.info("Waiting for active recording to finish...")
+        await job.finish()
+      }
+
+      if (running) await running.monitor.stop()
+    } finally {
+      clearTimeout(grace)
+    }
+    if (running) await running.http.close()
+    emitter.clear()
+    setState({ state: "stopped" })
+    logger.info("Recorder stopped")
+  }
+
+  return {
+    start,
+    stop,
+    getStatus: () => ({ ...status }),
+    on: emitter.on,
+    off: emitter.off,
+  }
+}
+
+function lastSource(verdict: ReturnType<typeof verdictOf>): string {
+  return (
+    [...verdict.evidence].reverse().find((e) => e.outcome === "hit" || e.outcome === "denied")
+      ?.source ?? "none"
+  )
+}

package/src/core/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * The single error type the library throws, plus its code union.
+ *
+ * Pure band: `io/` constructs it (`ffmpeg-error`, `aborted`) and `app/`
+ * constructs it (`config-error`), so it belongs below both.
+ */
+
+export type TikTokErrorCode =
+  | "config-error"
+  | "ffmpeg-not-found"
+  | "ffmpeg-error"
+  | "aborted"
+  | "unknown"
+
+export class TikTokError extends Error {
+  constructor(
+    public readonly code: TikTokErrorCode,
+    message: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message)
+    this.name = "TikTokError"
+  }
+}

package/src/core/format.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure formatting helpers — no I/O, no imports. Output filenames, byte counts,
+ * and human durations, shared by `io/` (download logging and output names) and
+ * the public API.
+ */
+
+/** Format a filename like username=2025.06.09_14-30-00_1.flv */
+export function formatFilename(user: string, ext = "flv", part?: number): string {
+  const now = new Date()
+  const pad = (n: number) => String(n).padStart(2, "0")
+  const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+  const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+  const partSuffix = part !== undefined ? `_part${part}` : ""
+  return `${user}=${date}_${time}${partSuffix}.${ext}`
+}
+
+/** Format bytes to human-readable size */
+export function bytesToHuman(bytes: number): string {
+  if (bytes === 0) return "0 B"
+  const units = ["B", "KB", "MB", "GB"]
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1)
+  return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`
+}
+
+/** Strip leading @ from a username */
+export function sanitizeUser(user: string): string {
+  return user.replace(/^@+/, "").trim()
+}
+
+/** Format a millisecond elapsed time as a relative human-readable string. */
+export function relativeTime(ms: number): string {
+  const sec = Math.floor(ms / 1000)
+  if (sec < 5) return "just now"
+  if (sec < 60) return `${sec}s ago`
+  const min = Math.floor(sec / 60)
+  if (min < 60) return `${min}m ago`
+  const hours = Math.floor(min / 60)
+  const mins = min % 60
+  if (hours < 24) return mins > 0 ? `${hours}h ${mins}m ago` : `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  return `${days}d ago`
+}
+
+/** Format seconds into a compact human-readable duration (e.g. "1m 5s", "30s"). */
+export function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  if (m > 0) return `${m}m ${s}s`
+  return `${s}s`
+}

package/src/core/log.ts

@@ -0,0 +1,13 @@
+/**
+ * Logger contract — the interface every adapter writes through.
+ *
+ * Pure band: `io/` may not import `app/`, and the adapters all take a logger.
+ * The rotating-file implementation is `app/logger.ts`.
+ */
+
+export interface Logger {
+  debug: (msg: string, ...args: unknown[]) => void
+  info: (msg: string, ...args: unknown[]) => void
+  warn: (msg: string, ...args: unknown[]) => void
+  error: (msg: string, ...args: unknown[]) => void
+}

package/src/core/plan.ts

@@ -0,0 +1,49 @@
+/**
+ * Tick policy — pure mapping from a `Verdict` plus facts to an action.
+ *
+ * No I/O, no clock, no promises. `session/` executes the returned plan.
+ */
+
+import type { RoomRef, StreamRef, Verdict } from "./verdict"
+
+export interface TickFacts {
+  readonly recording: boolean
+  readonly recordedSec: number
+  readonly oneShot: boolean
+  readonly consecutiveErrors: number
+}
+
+export type TickPlan =
+  | { kind: "poll"; note: string }
+  | { kind: "hold"; reason: "restricted" | "no-stream-url"; room: RoomRef }
+  | { kind: "record"; room: RoomRef; stream: StreamRef }
+  | { kind: "stop"; why: "one-shot" | "gave-up" }
+
+export function planTick(v: Verdict, f: TickFacts): TickPlan {
+  // No user-stop arm: `stop()` aborts the scope, which ends the poll loop before
+  // the next tick. A user stop is a signal, never a verdict.
+  switch (v.reason) {
+    case "live":
+      if (f.recording) return { kind: "poll", note: "already recording" }
+      if (!v.room || !v.stream) return { kind: "poll", note: "live without refs" }
+      return { kind: "record", room: v.room, stream: v.stream }
+
+    case "no-stream-url":
+    case "restricted":
+      if (!v.room) return { kind: "poll", note: "missing room" }
+      return { kind: "hold", reason: v.reason, room: v.room }
+
+    case "offline":
+      return f.oneShot && f.recordedSec > 0
+        ? { kind: "stop", why: "one-shot" }
+        : { kind: "poll", note: "offline" }
+
+    case "no-room-id":
+      return f.consecutiveErrors >= 10
+        ? { kind: "stop", why: "gave-up" }
+        : { kind: "poll", note: "no room" }
+
+    case "error":
+      return { kind: "poll", note: v.failure?.message ?? "error" }
+  }
+}

package/src/core/verdict.ts

@@ -0,0 +1,79 @@
+/**
+ * Verdict — the per-tick liveness result and its machine-readable reason.
+ *
+ * Pure domain type: no I/O, no imports outside `domain/`. `reason` is derived
+ * by `verdictOf`, never passed by callers; discovery reports facts, one total
+ * function decides what they mean.
+ */
+
+/**
+ * Machine-readable reason for a LIVE status verdict.
+ * "live" = stream URL resolved; "offline" = room not live;
+ * "restricted" = live but age-protected/gated (stream refused);
+ * "no-stream-url" = live but no URL and no gate evidence;
+ * "no-room-id" = no discovery path produced a room ID;
+ * "error" = network/parse failure across paths.
+ */
+export type LiveReason =
+  | "live"
+  | "offline"
+  | "restricted"
+  | "no-stream-url"
+  | "no-room-id"
+  | "error"
+
+export interface RoomRef {
+  readonly id: string
+  readonly title: string | null
+  readonly live: boolean
+}
+
+export interface StreamRef {
+  readonly url: string
+}
+
+/** Where a fact came from. Legacy `LiveInfo.source` values stay valid. */
+export type SourceId = "page" | "sigi" | "room-info" | "api-live" | "profile" | "none"
+
+export type EvidenceOutcome = "hit" | "miss" | "denied" | "error"
+
+export interface Evidence {
+  readonly source: SourceId
+  readonly outcome: EvidenceOutcome
+}
+
+export interface Verdict {
+  readonly reason: LiveReason
+  readonly room: RoomRef | null
+  readonly stream: StreamRef | null
+  readonly evidence: readonly Evidence[]
+  readonly failure: Error | null
+}
+
+/** Whether a reason means the room itself is live (holding or recording). */
+export function isLiveReason(reason: LiveReason): boolean {
+  return reason === "live" || reason === "restricted" || reason === "no-stream-url"
+}
+
+/**
+ * The single constructor for `Verdict`. Six branches cover every reason;
+ * precedence is failure → no room → offline → denied → live → no URL.
+ */
+export function verdictOf(x: {
+  room?: RoomRef | null
+  stream?: StreamRef | null
+  denied?: boolean
+  failure?: Error | null
+  evidence?: readonly Evidence[]
+}): Verdict {
+  const room = x.room ?? null
+  const stream = x.stream ?? null
+  const base = { room, stream, evidence: x.evidence ?? [], failure: x.failure ?? null }
+
+  if (x.failure) return { ...base, reason: "error" }
+  if (!room) return { ...base, reason: "no-room-id" }
+  if (!room.live) return { ...base, reason: "offline" }
+  if (x.denied) return { ...base, reason: "restricted" }
+  if (stream) return { ...base, reason: "live" }
+  return { ...base, reason: "no-stream-url" }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Library entry point — programmatic API for the TikTok Live Recorder.
+ *
+ * ```ts
+ * import { createRecorder } from 'tiktok-live-recorder-bun'
+ *
+ * const recorder = createRecorder({ user: 'username', outputDir: './videos' })
+ * recorder.on('recording:end', (info) => console.log('Done:', info.file))
+ * await recorder.start()
+ * ```
+ */
+
+export type {
+  LiveReason,
+  LogLevel,
+  Phase,
+  ProgressEvent,
+  RecordEvent,
+  RecordedFile,
+  RecorderConfig,
+  RecorderController,
+  RecorderEvent,
+  RecorderEventHandler,
+  RecorderStatus,
+} from "./app/config"
+export { createRecorder } from "./app/recorder"
+export type { TikTokErrorCode } from "./core/errors"
+export { TikTokError } from "./core/errors"
+export { bytesToHuman, formatDuration, relativeTime, sanitizeUser } from "./core/format"
+export type {
+  Evidence,
+  EvidenceOutcome,
+  RoomRef,
+  SourceId,
+  StreamRef,
+  Verdict,
+} from "./core/verdict"
+export { isLiveReason } from "./core/verdict"