@danything/arib 0.0.0-stage → 0.1.0

package/dist/eit.d.ts

@@ -0,0 +1,316 @@
+/**
+ * EIT を読む。番組表の中身そのもの。
+ *
+ * **denpa が自分で読む。** 番組表を誰かに聞きに行かないので、**チューナーが
+ * 空いているだけ並列に回せる**し、録画で開いているチャンネルのぶんはただで
+ * 手に入る ([agent.md](https://github.com/danything/denpa/blob/main/docs/agent.md))。
+ *
+ * 扱うのは2種類。
+ *
+ * - **EIT[p/f]** (table_id 0x4E) … いま流れている番組と次の番組。**放送に追従する。**
+ *   野球で延びた終了時刻はここに出る
+ * - **EIT[schedule]** (table_id 0x50〜0x5F) … 数日先までの番組表
+ *
+ * どちらも PID 0x0012 に流れてくる。
+ */
+interface EventAudio {
+    componentType: number;
+    langs: string[];
+    samplingRate?: number;
+    /**
+     * 放送が自分で付けた名前。**「主音声ステレオ」「解説ステレオ」。**
+     *
+     * 同じ構成の音声が2本ある番組 (解説放送・二重音声) は、種別も言語も同じに
+     * なるので**符号からは区別が付かない**。実機の日テレでは、どちらも
+     * `component_type=3 lang=jpn` で「ステレオ (日本語)」が2つ並んでいた。
+     * 見分けが付くものはここにしか無い
+     */
+    text?: string;
+    /** 主音声か (`main_component_flag`)。**解説放送はこちらが立っていないほう** */
+    main?: boolean;
+}
+/** ジャンル。大分類 (`lv1`) と中分類 (`lv2`) の番号 */
+export interface Genre {
+    lv1: number;
+    lv2: number;
+}
+export interface EitEvent {
+    serviceId: number;
+    transportStreamId: number;
+    originalNetworkId: number;
+    eventId: number;
+    /** 開始時刻 (epoch ms)。未定 (全ビット1) なら null */
+    startAt: number | null;
+    /** 尺 (ms)。未定なら null。番組表に入れられるのは決まっているものだけ */
+    duration: number | null;
+    isFree: boolean;
+    /** 1=まもなく 2=停止中 3=一時停止 4=放送中。p/f の「いま」を見分けるのに使う */
+    runningStatus: number;
+    name: string;
+    description: string;
+    /** 「出演者」などの見出し付き。extended_event_descriptor を繋ぎ直したもの */
+    extended: Record<string, string>;
+    /** content_descriptor の大分類・中分類 (ARIB STD-B10 付録 H) */
+    genres: Genre[];
+    audios: EventAudio[];
+    video: {
+        type: string | null;
+        resolution: string | null;
+    } | null;
+    /**
+     * **コピー禁止か** (デジタルコピー制御記述子)。禁止の番組は録らない (docs/data.md)。
+     *
+     * `null` は「この表は言っていない」。記述子は基本の表 (と p/f) に載り、詳細の表
+     * (0x58〜) には載らないので、詳細だけ届いた回で「禁止ではない」と上書きしないため
+     * (`EpgReader.merge`)
+     */
+    copyNever: boolean | null;
+}
+export interface EitSection {
+    tableId: number;
+    serviceId: number;
+    transportStreamId: number;
+    originalNetworkId: number;
+    version: number;
+    sectionNumber: number;
+    lastSectionNumber: number;
+    /** このセグメント (8セクション単位) で実際に使われている最後のセクション */
+    segmentLastSectionNumber: number;
+    /** この局で使われている最後の table_id。番組表がどこまで先を持っているか */
+    lastTableId: number;
+    events: EitEvent[];
+}
+/** TDT / TOT が流れている PID。**放送の現在時刻** */
+export declare const PID_TIME = 20;
+/**
+ * TDT / TOT のセクションから**放送の実時刻**を読む。別のテーブルなら null。
+ *
+ * 頭3バイトのあとに MJD + BCD が5バイト。**TOT も同じ並び**で、後ろに
+ * 時差の記述子が付くだけなので同じに読める。
+ *
+ * データ放送 (`bml.ts` の `onTime`) が読み、BML の時計にします
+ */
+export declare function parseTimeTable(section: Uint8Array): number | null;
+/**
+ * MJD + BCD の5バイトを epoch ms に直す。
+ *
+ * 全ビットが1なら「未定」。開始時刻が未定の番組は番組表に置けないので null で返す。
+ */
+export declare function parseMjdTime(data: Uint8Array, at: number): number | null;
+/** BCD 3バイトの尺 (時分秒) を ms に。全ビット1なら「終了未定」 */
+export declare function parseBcdDuration(data: Uint8Array, at: number): number | null;
+/**
+ * EIT のセクションを1本読む。自局のもの以外は null。
+ *
+ * 壊れたセクションは `SectionAssembler` が CRC で落としているので、ここに来るのは
+ * 中身が揃っているものだけ。それでも長さの辻褄が合わないことはあるので、
+ * **読める番組まで返す**。
+ */
+export declare function parseEit(section: Uint8Array, options?: {
+    other?: boolean;
+}): EitSection | null;
+/**
+ * どこまで集まったかを数える。
+ *
+ * **これが無いと「もう十分」が分からない。** 何分開いておくかを決め打ちにすると、
+ * 早く揃った局でも待たされ、遅い局は取りこぼす。EIT は自分がどこまであるかを
+ * セクションの中で言っているので、それを数えれば足りる。
+ *
+ * セクションは**8本ずつのセグメント**に分かれていて、セグメントの中で実際に
+ * 使われている最後の番号が `segment_last_section_number`。使われていない番号は
+ * 永久に来ないので、そこまで揃えばそのセグメントは終わり。
+ *
+ * **過ぎた時間帯のセグメントは流れてこない** (`stale`)。空でも先頭の1本は必ず
+ * 来るものとして待っていた頃は、**どのチャンネルも例外なく上限まで
+ * 開きっぱなし**になっていた (実機14チャンネル、揃って離せたのは0本)。
+ */
+export declare class ScheduleProgress {
+    private readonly now;
+    /** `table_id` → 受け取ったセクション番号 */
+    private readonly seen;
+    /** `table_id:セグメント先頭` → そのセグメントの最後の番号 */
+    private readonly segmentLast;
+    /** `table_id` → 最後のセクション番号 */
+    private readonly lastSection;
+    private lastTableId;
+    /**
+     * `table_id` → 版。変わったらその表だけ数え直す。
+     *
+     * **版は `table_id` ごとに別々に振られる。** 番組表の1つの表 (sub_table) は
+     * `table_id` + 局 + TS で決まり、`version_number` はその単位で動く。
+     * 局に1つだけ持っていた頃は、**基本 (0x50〜) と詳細 (0x58〜) を行き来する
+     * たびに版が違って数えたものを全部捨てて**いた。揃ったと分かることが
+     * 二度と無いので、どのチャンネルも上限の10分 (`epgChannelTimeout`) まで開きっぱなしになる。
+     */
+    private readonly version;
+    /**
+     * @param now いまの時刻。過ぎた時間帯を判断するのに使う。
+     *   時計を跨いで開いていることがあるので、値ではなく関数で受ける
+     */
+    constructor(now?: () => number);
+    add(section: EitSection): void;
+    /**
+     * 使われている table_id を全部揃えられたか。
+     *
+     * **番号が飛ぶ。** 1つの `table_id` が受け持つのは4日ぶんで、基本は
+     * `0x50` から、詳細は `0x58` から始まる。日本の放送は8日ぶんなので、
+     * 実際に流れてくるのは `0x50` `0x51` と `0x58` `0x59` あたりだけで、
+     * **`0x52`〜`0x57` は永久に来ません**。
+     *
+     * `0x50` から `last_table_id` まで全部を待っていた頃は、詳細を積んでいる局が
+     * **一度も「揃った」にならず**、どのチャンネルも上限の10分 (`epgChannelTimeout`) まで開きっぱなしに
+     * なっていました (実機で、詳細の無い BS11 だけが早く閉じていた)。
+     *
+     * 見かけた表と、`last_table_id` が指す表だけを見ます。
+     */
+    get complete(): boolean;
+    /** その表でまだ来ていない節。セグメントの先頭すら来ていなければ、先頭の番号を数える */
+    private holes;
+    /**
+     * そのセグメントの時間帯がもう過ぎているか。**過ぎたものは待たない。**
+     *
+     * セグメントは 0:00 から3時間ずつの枠で、`table_id` と節番号から
+     * それがいつの枠なのかが決まる — 基本は `0x50` が当日 0:00 から4日ぶん、
+     * `0x51` がその次の4日ぶん。詳細 (`0x58`〜) も同じ並びをもう一度たどる。
+     * 終わった枠は放送に乗らない (クラスの説明)。そのぶんの番組は、そこが未来だった数日前に取り込んである。
+     */
+    private stale;
+    /**
+     * 何が足りないか。**上限まで開いても揃わなかったときに出す。**
+     *
+     * 揃ったかどうかしか分からなかった頃は、上限まで開きっぱなしになっている局を
+     * 見つけても**その先を追えなかった** — 電波が弱くて欠けているのか、
+     * こちらが来ない表を待っているのかで、直し方がまるで違う。
+     */
+    report(): string;
+}
+/**
+ * 流れてくる TS を食べて番組を溜める。
+ *
+ * 局ごとに `ScheduleProgress` を持ち、**その物理チャンネルに入っている局が
+ * 全部揃ったら**読むのをやめられる。同じ番組が何度も来る (カルーセルなので) ので、
+ * event_id で上書きしていく。
+ */
+export declare class EpgReader {
+    private readonly now;
+    private readonly options;
+    private readonly sections;
+    private readonly packets;
+    private readonly progress;
+    /** `serviceId:eventId` → 番組。あとから来たもので上書きする */
+    private readonly events;
+    /** p/f で「いま流れている」と言われた番組。録画の延長追従はこれを見る */
+    readonly present: Map<number, EitEvent>;
+    /** `takeChanged` のあとに増えた・変わった番組 (`serviceId:eventId`) */
+    private readonly changed;
+    /** 最後に新しい局を見かけた時刻 (`other` のときだけ使う) */
+    private lastNewService;
+    /**
+     * @param now いまの時刻。局ごとの `ScheduleProgress` にそのまま渡す
+     * @param options.other ほかの TS の局の番組表も読む。ネットワーク全局ぶんを
+     *   1つの中継から先に入れるときに使う (`epg-collect.ts` の初回)
+     * @param options.settle `other` のとき、新しい局が出てこなくなってから閉じるまで (ms)
+     * @param options.expect `other` のとき、来るはずの局 (service_id)。全部見えて揃えば
+     *   `settle` を待たずに閉じる。受信できない局が混ざっていれば `settle` で閉じる
+     */
+    constructor(now?: () => number, options?: {
+        other?: boolean;
+        settle?: number;
+        expect?: readonly number[];
+    });
+    /** 任意の長さのバイト列を食わせる。番組が1つでも増えたら true */
+    feed(chunk: Uint8Array): boolean;
+    /**
+     * 溜めてあるものと混ぜる。**別の表で来るものを消し合わせない。**
+     *
+     * 番組表は2つの表に分かれて流れてくる。同じ event_id が両方に載っていて、
+     * **それぞれ自分のぶんの記述子しか持っていない**。
+     *
+     * - **基本** (table_id 0x50〜0x57) … タイトルと短い説明 (short_event_descriptor)
+     * - **詳細** (0x58〜0x5F) … 「番組内容」「出演者」など (extended_event_descriptor)
+     *
+     * あとから来たもので丸ごと置き換えていた頃は、**詳細のほうが後に届いた番組の
+     * タイトルが空になっていた**。実機では番組 23,000 件のうち 11,000 件が名無しで、
+     * うち 2,700 件は「タイトルは無いのに番組内容だけある」状態 — 詳細に上書きされた
+     * 跡そのもの。番組表には「(番組情報なし)」の列が並んでいた。
+     *
+     * **中身のあるほうを残す。** 書き換え (「[新]」が付く、誤字が直る) は
+     * 空でない値で来るので、これまでどおり新しいほうが勝つ。
+     */
+    private merge;
+    /**
+     * p/f で「いま流れている」と言えるか。
+     *
+     * **`running_status` を当てにしきれない。** 4 (放送中) を入れてくる局も
+     * あれば、**0 (未定義) しか入れてこない局もある** — 実機の NHK は 74 節
+     * ぜんぶ 0 だった。4 だけを見ていると、そういう局では延長追従が丸ごと
+     * 効かなくなる (docs/agent.md)。
+     *
+     * そこで 0 のときは**節の番号で決める**。p/f は仕様で
+     * **section 0 が現在・section 1 が次**と決まっていて、こちらは局の都合で
+     * 変わらない。1 (まもなく) や 2 (停止中) は今までどおり入れない。
+     */
+    private onAir;
+    /**
+     * 前に呼んでから増えた・変わった番組。**読みながら少しずつ保存する**ため
+     * (`epg-collect.ts`)。揃うまで待ってからまとめて書くと、全局読みの数分のあいだ
+     * 画面に何も出ない
+     */
+    takeChanged(): EitEvent[];
+    /** 書けなかったぶんを、次の `takeChanged` でもう一度返す */
+    requeue(events: EitEvent[]): void;
+    /** 溜まった番組。開始時刻の順に並べて返す */
+    all(): EitEvent[];
+    /** 番組表を1つでも見かけた局 */
+    services(): number[];
+    /**
+     * 見かけた局が**全部**揃ったか。
+     *
+     * 「1局でも揃えば閉じる」にはしない。1つの物理チャンネルには複数の局が
+     * 入っていて (地上波なら MX1 と MX2)、先に揃ったほうで閉じると残りが
+     * 永久に埋まらない。
+     */
+    get complete(): boolean;
+    /** 来るはずの局を教わっていて、それが全部見えたか */
+    private sawExpected;
+    /**
+     * 揃っていない局と、その理由。**上限まで開いてしまったときに出す。**
+     *
+     * 1局でも揃わなければチャンネルごと上限まで開き続けるので、
+     * 「どの局のせいか」が分からないと直しようがない。
+     */
+    shortfall(): string[];
+}
+/**
+ * **1局の「いま」と「次」(EIT[p/f]) を追う。** ライブで番組の切り替わりを知るのに使う。
+ *
+ * 番組表 (schedule) は数日先までの予定で、**延長や繰り下げには追いつかない**
+ * (局が送り直してくるのは後になってから)。p/f は放送そのものに追従していて、
+ * 野球が延びれば「いま」の尺が延び、終われば「次」が「いま」に繰り上がる。
+ *
+ * section 0 が「いま」、section 1 が「次」と決まっている (`EpgReader.onAir` と同じ)。
+ *
+ * **中身で比べる。** 書き換われば version が上がるはずだが、上げずに中身だけ替える
+ * 送り手を当てにしないよう、番組の番号・時刻・尺・タイトルで比べる。p/f は1局ぶん数百バイトが
+ * 数秒おきに来るだけなので、毎回読んでも軽い
+ */
+export declare class PresentFollowing {
+    private readonly serviceId;
+    private readonly sections;
+    /** section 0 (いま) と 1 (次) で最後に読んだ番組。来ていなければ null */
+    private readonly held;
+    /** 中身の印 (`mark`)。同じものが繰り返し来ても変わったと言わない */
+    private readonly marks;
+    /** @param serviceId 追う局 (放送が名乗っている service_id) */
+    constructor(serviceId: number);
+    /** いま流れている番組。まだ来ていない・放送が空けているなら null */
+    get present(): EitEvent | null;
+    /** 次の番組 */
+    get following(): EitEvent | null;
+    /**
+     * 188 バイトのパケットを1つ。**いまか次のどちらかが変わったら true**。
+     * 最初に読めたときも true (知らなかったものが分かった)
+     */
+    feedPacket(packet: Uint8Array): boolean;
+}
+export {};