@danything/arib 0.0.0-stage → 0.1.0

package/dist/bml.js

@@ -0,0 +1,489 @@
+/**
+ * データ放送 (ARIB STD-B24 の BML) をデコードする。**1局に絞った TS を食わせると、
+ * 組み立て終わったファイルが出てくる。**
+ *
+ *     TS → PAT → PMT → データ符号化方式記述子 (0xFD) の付いた ES
+ *                       → DII/DDB (カルーセル) → モジュール → ファイル
+ *
+ * ## なぜ自前なのか
+ *
+ * **運び方は衛星のロゴと同じ DSM-CC** で、denpa はそれを既に持っている
+ * ([dsmcc.ts](dsmcc.ts) / [logo-dsmcc.ts](https://github.com/danything/denpa/blob/main/src/lib/ts/logo-dsmcc.ts))。
+ * [web-bml](https://github.com/otya128/web-bml) の `decode_ts.ts` は使わない — 要るのは
+ * その一部だけで、残り (EIT/SDT/NIT・字幕の PES) は自前で読んでおり
+ * ([eit.ts](eit.ts) / [psi.ts](psi.ts) / ffmpeg)、`@chinachu/aribts` も抱えずに済む。
+ *
+ * **出す形式は web-bml の頃のまま** ([bml-protocol.ts](bml-protocol.ts))。録画の隣の
+ * `.bml.jsonl` がこの形式で残っているので、変えると前に録ったものが読めなくなる。
+ * モジュールの中身 (multipart) は [multipart.ts](multipart.ts) がデコードする。
+ */
+import { Buffer } from "node:buffer";
+import { inflateSync } from "node:zlib";
+import { u16, u32 } from "./bytes.js";
+import { dataEventIdOf, ModuleBuilder, parseDdb, parseDii, TABLE_DII, TABLE_STREAM_DESCRIPTOR, } from "./dsmcc.js";
+import { parseTimeTable, PID_TIME } from "./eit.js";
+import { parseMediaType, readEntity } from "./multipart.js";
+import { descriptors, packetPid, PacketStream, pmtStreams, PmtTracker, SectionAssembler, } from "./psi.js";
+const DESC_STREAM_IDENTIFIER = 0x52;
+/** データ符号化方式記述子 (STD-B10 第2部 6.2.20) */
+const DESC_DATA_COMPONENT = 0xfd;
+/**
+ * BML が載っている符号化方式 (STD-B10 第2部 付録J 表J-1)。
+ * 0x0C/0x0D が地上波、0x07 が BS、0x0B が CS
+ */
+const BXML_COMPONENT_IDS = new Set([0x07, 0x0b, 0x0c, 0x0d]);
+/** zlib。Compression Type 記述子で運用されるのはこれだけ */
+const COMPRESSION_ZLIB = 0;
+/**
+ * データ符号化方式記述子の後半を読む。
+ *
+ * 地上波は TR-B14 第二分冊 2.1.4 表2-3、BS/CS は TR-B15 第一分冊 5.1.5 表5-4。
+ *
+ * **`data_component_id` は16ビット** (aribts は8ビットで読んでいる)。
+ */
+export function parseBxmlInfo(data) {
+    let at = 0;
+    // 00 のみ運用 (データカルーセル伝送方式およびイベントメッセージ伝送方式)
+    const transmissionFormat = (data[at] >> 6) & 0b11;
+    // component_tag=0x40 のとき必ず1。startup.xml が最初に起動される
+    const entryPointFlag = ((data[at] >> 5) & 1) === 1;
+    const info = { transmissionFormat, entryPointFlag };
+    if (entryPointFlag) {
+        const autoStartFlag = ((data[at] >> 4) & 1) === 1;
+        /*
+         * 画面の大きさ。運用されるのは 0011 (960x540)、0100 (640x480 16:9)、
+         * 0101 (640x480 4:3) の3つ
+         */
+        const documentResolution = data[at] & 0x0f;
+        at++;
+        const useXML = ((data[at] >> 7) & 1) === 1;
+        const defaultVersionFlag = ((data[at] >> 6) & 1) === 1;
+        // BS/CS では 0 のとき単独視聴不可。地上波は常に1
+        const independentFlag = ((data[at] >> 5) & 1) === 1;
+        const styleForTVFlag = ((data[at] >> 4) & 1) === 1;
+        at++;
+        // 既定は BS の 1.0。地上波は3、CS は2が入ってくる
+        info.entryPointInfo = {
+            autoStartFlag,
+            documentResolution,
+            useXML,
+            defaultVersionFlag,
+            independentFlag,
+            styleForTVFlag,
+            bmlMajorVersion: 1,
+            bmlMinorVersion: 0,
+        };
+        if (!defaultVersionFlag) {
+            info.entryPointInfo.bmlMajorVersion = u16(data, at);
+            info.entryPointInfo.bmlMinorVersion = u16(data, at + 2);
+            at += 4;
+            // 運用されない
+            if (useXML) {
+                info.entryPointInfo.bxmlMajorVersion = u16(data, at);
+                info.entryPointInfo.bxmlMinorVersion = u16(data, at + 2);
+                at += 4;
+            }
+        }
+    }
+    else {
+        at++;
+    }
+    if (transmissionFormat === 0) {
+        // additional_arib_carousel_info (STD-B24 第三分冊 第三編 C.1)
+        const dataEventId = (data[at] >> 4) & 0x0f;
+        const eventSectionFlag = ((data[at] >> 3) & 1) === 1;
+        at++;
+        const ondemandRetrievalFlag = ((data[at] >> 7) & 1) === 1;
+        const fileStorableFlag = ((data[at] >> 6) & 1) === 1;
+        const startPriority = (data[at] >> 5) & 1;
+        info.additionalAribCarouselInfo = {
+            dataEventId,
+            eventSectionFlag,
+            ondemandRetrievalFlag,
+            fileStorableFlag,
+            startPriority,
+        };
+    }
+    return info;
+}
+/**
+ * PMT から ES を並べる。**部品タグ (component_tag) を持たない ES は数に入れない** —
+ * データ放送は「何番の部品か」でしか物を指せないので、番号の無いものは指しようがない。
+ */
+function parsePmt(section) {
+    const components = [];
+    for (const [streamType, pid, info] of pmtStreams(section)) {
+        let componentId;
+        let dataComponentId;
+        let bxmlInfo;
+        for (const [tag, descriptor] of descriptors(info)) {
+            if (tag === DESC_STREAM_IDENTIFIER && descriptor.length >= 1)
+                componentId = descriptor[0];
+            else if (tag === DESC_DATA_COMPONENT && descriptor.length >= 2) {
+                dataComponentId = u16(descriptor, 0);
+                if (BXML_COMPONENT_IDS.has(dataComponentId))
+                    bxmlInfo = parseBxmlInfo(descriptor.subarray(2));
+            }
+        }
+        if (componentId === undefined)
+            continue;
+        components.push({
+            componentId,
+            pid,
+            streamType,
+            ...(dataComponentId === undefined ? {} : { dataComponentId }),
+            ...(bxmlInfo === undefined ? {} : { bxmlInfo }),
+        });
+    }
+    return components;
+}
+/** `at` の下位1ビットと続く4バイトで 33 ビット (STC・NPT) */
+const u33 = (data, at) => (data[at] & 1) * 0x100000000 + u32(data, at + 1);
+/** ストリーム記述子 (table_id 0x3D)。NPT と イベントメッセージが載っている */
+function parseEsEvents(section) {
+    const events = [];
+    const length = u16(section, 1) & 0x0fff;
+    const body = section.subarray(8, Math.min(3 + length - 4, section.length));
+    for (const [tag, descriptor] of descriptors(body)) {
+        if (tag === 0x17 && descriptor.length >= 18) {
+            // NPT 参照記述子。放送の時計と番組内の時刻を結び付ける
+            events.push({
+                type: "nptReference",
+                postDiscontinuityIndicator: (descriptor[0] & 0x80) !== 0,
+                dsmContentId: descriptor[0] & 0x7f,
+                STCReference: u33(descriptor, 1),
+                NPTReference: u33(descriptor, 9),
+                scaleNumerator: u16(descriptor, 14),
+                scaleDenominator: u16(descriptor, 16),
+            });
+        }
+        else if (tag === 0x40 && descriptor.length >= 11) {
+            // 汎用イベントメッセージ記述子。運用されるのは time_mode 0 と 2 だけ
+            const timeMode = descriptor[2];
+            const message = {
+                eventMessageGroupId: (u16(descriptor, 0) >> 4) & 0x0fff,
+                eventMessageType: descriptor[8],
+                eventMessageId: u16(descriptor, 9),
+                privateDataByte: [...descriptor.subarray(11)],
+            };
+            if (timeMode === 0)
+                events.push({ type: "immediateEvent", timeMode: 0, ...message });
+            else if (timeMode === 2)
+                events.push({
+                    type: "nptEvent",
+                    timeMode: 2,
+                    eventMessageNPT: u33(descriptor, 3),
+                    ...message,
+                });
+        }
+    }
+    return events;
+}
+/**
+ * **DII に載ったモジュールが来なければ諦める。** 最後にブロックが増えてから、DII が
+ * この回数繰り返し、しかもカルーセルが一覧の大きさのこの倍数ぶん流れたら、もう来ないとみなす。
+ * 両方を見るのは、DII の繰り返しはカルーセルの一周より短いことがあり (回数だけだと大きい
+ * カルーセルの途中で諦める)、よく使うモジュールは一周に何度も流れる (バイト数だけだと一周を
+ * 短く見積もる) ため
+ */
+const GIVE_UP_ROUNDS = 4;
+/** `Component.done` に置く印。モジュールの版とカルーセルの回 (dataEventId) の組 */
+function doneMark(component, version) {
+    return `${version}:${component.dataEventId}`;
+}
+/**
+ * 1局に絞った TS を食わせると、データ放送の通知が出てくる。
+ *
+ * **1つの選局に1つ。** 局を変えたら作り直す — カルーセルは局ごとに別物で、
+ * 組み立て中のものを持ち越すと混ざる。
+ */
+export class BmlDecoder {
+    send;
+    packets = new PacketStream();
+    /** **1局に絞ったあとを食わせる前提。** 入っているサービスは1つなので、最初の局の PMT を追う */
+    pmt = new PmtTracker();
+    // TDT は CRC を持たない。DSM-CC と同じ理由で 'syntax' で受ける
+    time = new SectionAssembler(PID_TIME, "syntax");
+    /** カルーセルが流れている ES。PID ごと */
+    components = new Map();
+    /** 最後に配った PMT。**変わったときだけ配る** */
+    sent = null;
+    constructor(send) {
+        this.send = send;
+    }
+    /** 1局に絞った TS を食わせる */
+    feed(chunk) {
+        for (const packet of this.packets.feed(chunk))
+            this.feedPacket(packet);
+    }
+    /**
+     * 切り分け済みのパケットを1つ。ライブは同じ TS を時計や Hybridcast とも
+     * 分け合うので、切り分けは1回で済ませて配る (`server/live.ts` の `tap`)。
+     *
+     * **PID で行き先を引く。** 組み立て役を全部に回していた頃は、データ放送と
+     * 関係ない映像のパケットのたびにカルーセルの数だけ呼んでいた。
+     *
+     * `packet` は呼び手の塊の上の窓 (`psi.ts` の `PacketStream`)。**返ったあとまで
+     * 持つなら写すこと** — 塊の入れ物は使い回される
+     */
+    feedPacket(packet) {
+        const pid = packetPid(packet);
+        // 同じ PID を2役が名乗ることもあるので、else でつながない
+        for (const section of this.pmt.feed(packet, pid))
+            this.onPmt(section);
+        if (pid === PID_TIME)
+            for (const section of this.time.feed(packet))
+                this.onTime(section);
+        const component = this.components.get(pid);
+        if (component !== undefined) {
+            for (const section of component.sections.feed(packet))
+                this.onCarousel(component, section);
+        }
+    }
+    onPmt(section) {
+        const components = parsePmt(section);
+        if (components.length === 0)
+            return;
+        /*
+         * 放送は同じ表を何度も送る。**変わったときだけ配る** — 受け側は
+         * PMT が来るたびに画面を組み直すので、そのまま通すと出っ放しになる
+         */
+        const shape = JSON.stringify(components);
+        if (this.sent !== shape) {
+            this.sent = shape;
+            this.send({ type: "pmt", components });
+        }
+        for (const component of components) {
+            // カルーセルが流れているのは、BML の符号化方式が付いた ES だけ
+            if (component.bxmlInfo === undefined)
+                continue;
+            if (this.components.has(component.pid))
+                continue;
+            this.components.set(component.pid, {
+                componentId: component.componentId,
+                // DSM-CC は section_syntax_indicator が立たないことがある (psi.ts)
+                sections: new SectionAssembler(component.pid, "syntax"),
+                transactionId: null,
+                dataEventId: -1,
+                building: new Map(),
+                done: new Map(),
+                dii: null,
+                size: 0,
+                abandoned: new Set(),
+            });
+        }
+    }
+    /** TDT / TOT。読み方は [eit.ts](eit.ts) にまとめてある */
+    onTime(section) {
+        const at = parseTimeTable(section);
+        if (at !== null)
+            this.send({ type: "currentTime", timeUnixMillis: at });
+    }
+    onCarousel(component, section) {
+        if (section[0] === TABLE_STREAM_DESCRIPTOR) {
+            const extension = u16(section, 3);
+            this.send({
+                type: "esEventUpdated",
+                componentId: component.componentId,
+                events: parseEsEvents(section),
+                dataEventId: extension >> 12,
+            });
+            return;
+        }
+        if (section[0] === TABLE_DII)
+            this.onDii(component, section);
+        else
+            this.onDdb(component, section);
+    }
+    onDii(component, section) {
+        const dii = parseDii(section);
+        if (dii === null)
+            return;
+        // 同じカルーセルが回ってきただけ。組み立て中のものを捨てない
+        if (component.transactionId === dii.transactionId) {
+            for (const held of component.building.values())
+                held.quietDiis++;
+            this.giveUp(component);
+            return;
+        }
+        component.transactionId = dii.transactionId;
+        /*
+         * **番組が変わったら覚えていたものを捨てる。** dataEventId はカルーセルの
+         * 「回」で、ここが変わると前の番組のファイルは使えない
+         */
+        const dataEventId = dataEventIdOf(dii.downloadId);
+        if (component.dataEventId !== dataEventId) {
+            component.dataEventId = dataEventId;
+            component.done.clear();
+        }
+        component.building.clear();
+        component.abandoned.clear();
+        component.dii = dii;
+        component.size = 0;
+        for (const module of dii.modules) {
+            component.size += module.moduleSize;
+            component.building.set(module.moduleId, {
+                module,
+                builder: new ModuleBuilder(module.moduleVersion, module.moduleSize, dii.blockSize),
+                quietDiis: 0,
+                quietBytes: 0,
+            });
+        }
+        this.sendList(component);
+        // 大きさ 0 のものは DDB が来ない。待たせずに配る (来ないまま諦めると、受け側は無いものと見なす)
+        for (const [moduleId, held] of component.building) {
+            if (held.builder.complete)
+                this.finish(component, moduleId, held);
+        }
+    }
+    /** 今の DII の一覧を配る。**諦めたモジュールは載せない** */
+    sendList(component) {
+        const dii = component.dii;
+        if (dii === null)
+            return;
+        this.send({
+            type: "moduleListUpdated",
+            componentId: component.componentId,
+            modules: dii.modules
+                .filter((module) => !component.abandoned.has(module.moduleId))
+                .map((module) => ({
+                id: module.moduleId,
+                version: module.moduleVersion,
+                size: module.moduleSize,
+            })),
+            dataEventId: component.dataEventId,
+            ...(dii.returnToEntry === null
+                ? {}
+                : { returnToEntryFlag: dii.returnToEntry }),
+        });
+    }
+    /**
+     * **来ないモジュールを諦める** (`GIVE_UP_ROUNDS`)。待っている受け側 (`Resources` の `wait`) は、
+     * DII に無いモジュールを「もう来ない」と決める (`gone`) ので、諦めたものを除いた一覧を配り直して
+     * 待ちを終わらせる。前の DII で配り終えた版のままのもの (受け側が持っている) は一覧から外さず、
+     * 組み立てるのをやめるだけ。次に DII の版が変われば、また待つ
+     */
+    giveUp(component) {
+        const limit = component.size * GIVE_UP_ROUNDS;
+        let changed = false;
+        for (const [moduleId, held] of component.building) {
+            if (held.quietDiis < GIVE_UP_ROUNDS || held.quietBytes < limit)
+                continue;
+            component.building.delete(moduleId);
+            if (component.done.get(moduleId) ===
+                doneMark(component, held.module.moduleVersion))
+                continue;
+            component.abandoned.add(moduleId);
+            changed = true;
+        }
+        if (changed)
+            this.sendList(component);
+    }
+    onDdb(component, section) {
+        const ddb = parseDdb(section);
+        if (ddb === null)
+            return;
+        for (const waiting of component.building.values())
+            waiting.quietBytes += ddb.block.length;
+        const held = component.building.get(ddb.moduleId);
+        // 版が食い違うブロックを混ぜると壊れたファイルができる
+        if (held === undefined || held.builder.moduleVersion !== ddb.moduleVersion)
+            return;
+        const before = held.builder.blocks;
+        const complete = held.builder.add(ddb.blockNumber, ddb.block);
+        if (held.builder.blocks > before) {
+            held.quietDiis = 0;
+            held.quietBytes = 0;
+        }
+        if (complete)
+            this.finish(component, ddb.moduleId, held);
+    }
+    /** 揃ったモジュールを配る */
+    finish(component, moduleId, held) {
+        // 次の DII が来るまで組み立て直さない
+        component.building.delete(moduleId);
+        /*
+         * **同じものを配り直さない。** カルーセルは回り続けるので、版が上がって
+         * いなくても同じモジュールが何度も揃う。そのたびに配ると、受け側は
+         * 中身の変わらない画面を組み直し続ける
+         */
+        const version = held.builder.moduleVersion;
+        const mark = doneMark(component, version);
+        if (component.done.get(moduleId) === mark)
+            return;
+        component.done.set(moduleId, mark);
+        // 大きさ 0 は伸ばしようが無い。ファイルの無いモジュールとして配り、待っている受け側を終わらせる
+        const empty = held.module.moduleSize === 0;
+        const data = empty
+            ? held.builder.data
+            : inflate(held.builder.data, held.module.compression);
+        if (data === null)
+            return;
+        const files = moduleFiles(data, held.module.contentType);
+        if (files.length === 0 && !empty)
+            return;
+        this.send({
+            type: "moduleDownloaded",
+            componentId: component.componentId,
+            moduleId,
+            files,
+            version,
+            dataEventId: component.dataEventId,
+        });
+    }
+}
+/**
+ * 揃ったモジュールをファイルに分ける。
+ *
+ * **多くは `multipart/mixed`** で、1つのモジュールに BML と画像がまとめて
+ * 入っている。Type 記述子が無いときも中身は multipart なので、同じ扱いにする。
+ */
+export function moduleFiles(data, contentType) {
+    const declared = contentType === null ? null : parseMediaType(contentType);
+    if (declared !== null &&
+        !(declared.type === "multipart" && declared.subtype === "mixed")) {
+        return [
+            {
+                contentLocation: null,
+                contentType: declared,
+                dataBase64: base64(data),
+            },
+        ];
+    }
+    const entity = readEntity(data);
+    if (entity?.parts == null)
+        return [];
+    const files = [];
+    for (const part of entity.parts) {
+        const location = part.headers.find((header) => header.name === "content-location");
+        const type = part.headers.find((header) => header.name === "content-type");
+        // どちらも必ず入っている。欠けているものは置き場所も読み方も分からない
+        if (location === undefined || type === undefined)
+            continue;
+        const mediaType = parseMediaType(type.value);
+        if (mediaType === null)
+            continue;
+        files.push({
+            contentLocation: location.value,
+            contentType: mediaType,
+            dataBase64: base64(part.body),
+        });
+    }
+    return files;
+}
+function base64(data) {
+    return Buffer.from(data).toString("base64");
+}
+/** zlib で縮めてあれば伸ばす。伸ばせなければ諦めて null */
+export function inflate(data, compression) {
+    if (compression === null)
+        return data;
+    if (compression.type !== COMPRESSION_ZLIB)
+        return null;
+    try {
+        return inflateSync(data);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bytes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * バイト列の細かい道具。**中身の意味は持たない。** 繋ぐ・読むのはここで済ませる (別名で書き直さない)
+ */
+/** バイト列を新しい1本に繋ぐ (いつも写す。`Blob` などへ渡せる `ArrayBuffer` の上に作る) */
+export declare function concatBytes(parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer>;
+/**
+ * バイト列を1本に繋ぐ。
+ *
+ * **1本しかないときは写しません。** 分割された記述子を繋ぎ直すところ
+ * ([eit.ts](eit.ts)) では、繋ぐ必要のないほうが多数です
+ */
+export declare function joinBytes(parts: readonly Uint8Array[]): Uint8Array;
+/** 大きい桁が先の 16 ビット */
+export declare function u16(data: Uint8Array, at: number): number;
+/** 大きい桁が先の 24 ビット */
+export declare function u24(data: Uint8Array, at: number): number;
+/** 大きい桁が先の 32 ビット (符号なし) */
+export declare function u32(data: Uint8Array, at: number): number;
+/** `length` バイトをそのまま1字ずつの文字列に (MP4 の箱の種別・PNG の塊の名前・言語の符号) */
+export declare function ascii(data: Uint8Array, at: number, length: number): string;

package/dist/bytes.js

@@ -0,0 +1,45 @@
+/**
+ * バイト列の細かい道具。**中身の意味は持たない。** 繋ぐ・読むのはここで済ませる (別名で書き直さない)
+ */
+/** バイト列を新しい1本に繋ぐ (いつも写す。`Blob` などへ渡せる `ArrayBuffer` の上に作る) */
+export function concatBytes(parts) {
+    let total = 0;
+    for (const part of parts)
+        total += part.length;
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of parts) {
+        out.set(part, at);
+        at += part.length;
+    }
+    return out;
+}
+/**
+ * バイト列を1本に繋ぐ。
+ *
+ * **1本しかないときは写しません。** 分割された記述子を繋ぎ直すところ
+ * ([eit.ts](eit.ts)) では、繋ぐ必要のないほうが多数です
+ */
+export function joinBytes(parts) {
+    return parts.length === 1 ? parts[0] : concatBytes(parts);
+}
+/** 大きい桁が先の 16 ビット */
+export function u16(data, at) {
+    return (data[at] << 8) | data[at + 1];
+}
+/** 大きい桁が先の 24 ビット */
+export function u24(data, at) {
+    return (data[at] << 16) | u16(data, at + 1);
+}
+/** 大きい桁が先の 32 ビット (符号なし) */
+export function u32(data, at) {
+    return (((data[at] << 24) |
+        (data[at + 1] << 16) |
+        (data[at + 2] << 8) |
+        data[at + 3]) >>>
+        0);
+}
+/** `length` バイトをそのまま1字ずつの文字列に (MP4 の箱の種別・PNG の塊の名前・言語の符号) */
+export function ascii(data, at, length) {
+    return String.fromCharCode(...data.subarray(at, at + length));
+}

package/dist/caption-text.d.ts

@@ -0,0 +1,122 @@
+/**
+ * **字幕の文字の配置** (第1版)。サーバが放送の字幕 (ARIB STD-B24) をデコードして置き場所まで
+ * 決め、受け側 (ブラウザ・テレビのアプリ) はこれを**描くだけ**にする。形式の取り決めは
+ * [api.md](https://github.com/danything/denpa/blob/main/docs/api.md#字幕の文字の配置) に書いてある (ここと同じものを、Kotlin でも読む)。
+ *
+ * 座標はすべて**字幕の面の単位** (`plane`。ふつう 960x540)。受け側は映像の枠に
+ * 合わせて縦横それぞれ伸ばす。色は `#rrggbbaa`。
+ */
+/** 形式の版。**互換の無い変え方をしたら上げる** (受け側は知らない版を描かない) */
+export declare const CAPTION_TEXT_VERSION = 1;
+/** 縁取り (ORN) の太さ。面の単位で、字の輪郭の外側へ。libaribcaption の既定 (ffmpeg の `outline_width`) と同じ */
+export declare const STROKE_WIDTH = 1.5;
+/** 点滅 (FLC) の間 (ms)。出ている時間と消えている時間 */
+export declare const FLASH_MS = 500;
+/** 字幕1枚。**前の1枚を丸ごと置き換える** (`runs` が空なら消す) */
+export interface CaptionPage {
+    v: typeof CAPTION_TEXT_VERSION;
+    /** 字幕の面の大きさ [幅, 高さ] */
+    plane: [number, number];
+    /** 出しておく長さ (ms)。null なら次の1枚まで */
+    duration: number | null;
+    /** 字の並び。描く順 */
+    runs: CaptionRun[];
+    /** 置き換えられなかった外字の画像。`CaptionRun.drcs` で引く */
+    drcs?: Record<string, CaptionDrcs>;
+}
+/**
+ * 同じ見た目で横に並ぶ字。`text` の1字 (コードポイント) ごとに、幅 `w` の区画を
+ * `x` から右へ1つずつ使う。
+ */
+export interface CaptionRun {
+    /** 1字目の区画の左上 */
+    x: number;
+    y: number;
+    /** 区画1つの幅・高さ。背景 (`bg`) はこの広さを塗る */
+    w: number;
+    h: number;
+    /** 区画の左上から、字の枠の左上まで */
+    fx: number;
+    fy: number;
+    /** 字の大きさ (em)。字の枠の高さでもある */
+    size: number;
+    /**
+     * 横の縮め方。字の枠の幅は `size * scaleX`。中くらい (MSZ) の全角は 0.5 で縮めて描き、
+     * 半角の字 (英数・半角カナ) は 1 のまま (もともと半分の幅なので)
+     */
+    scaleX: number;
+    text: string;
+    /** 置き換えられなかった外字。`text` は「〓」で、この画像を字の枠いっぱいに描く */
+    drcs?: string;
+    /** 字の色 */
+    fg: string;
+    /** 背景の色 (区画) */
+    bg: string;
+    /** 縁取りの色 (ORN)。無ければ縁取らない */
+    stroke?: string;
+    underline?: true;
+    bold?: true;
+    italic?: true;
+    /** 囲み (HLC)。1 下・2 右・4 上・8 左の和。線は字の色で、太さは面の 1 単位 */
+    box?: number;
+    /** 点滅 (FLC) */
+    flash?: true;
+    /** ルビらしい小さな字 (libaribcaption と同じ見分け方) */
+    ruby?: true;
+}
+/** 外字の画像。`data` は base64 で、左上から1画素 `bits` ビットずつ (上の桁から) 詰めたもの */
+export interface CaptionDrcs {
+    w: number;
+    h: number;
+    /** 階調の数 (2 なら白黒)。値 v の濃さは v / (depth - 1) */
+    depth: number;
+    bits: number;
+    data: string;
+    /**
+     * 放送の元の画像の MD5。外字の置き換え表 (`b24-tables.ts` の `DRCS_REPLACE`) に足すときに使う。
+     * `data` は送るためになめらかにした画像なので、その MD5 は表と合わない。描くのには使わない
+     */
+    md5?: string;
+}
+/** 空白として字を描かない (背景だけ塗る) 字。libaribcaption の IsSpaceCharacter と同じ */
+export declare function isSpace(code: number): boolean;
+/** 録画1本ぶんの字幕 (`GET /api/recordings/<id>/captions.json`)。`at` は動画の頭からの秒 */
+export interface CaptionPages {
+    v: typeof CAPTION_TEXT_VERSION;
+    /** 第1言語 */
+    pages: {
+        at: number;
+        page: CaptionPage;
+    }[];
+    /** 第1言語の名前。字幕管理データが読めなければ省く */
+    language?: CaptionLanguage;
+    /** 第2言語から後ろ。**載っているときだけ** (たいていの番組は第1言語だけ) */
+    others?: CaptionLanguagePages[];
+}
+/**
+ * 字幕の言語1つ。**ARIB の字幕は1本の中に最大8言語を持てる** (データグループの番号 1〜8。
+ * 何番がどの言語かは字幕管理データに ISO 639 の3文字で書いてある)。日本の放送はほぼ日本語だけで、
+ * 英語の字幕が付く番組がたまにある
+ */
+export interface CaptionLanguage {
+    /** 第何言語か (1〜8。データグループの番号) */
+    index: number;
+    /** ISO 639-2 の3文字 (`jpn` / `eng`)。読めなければ空 */
+    code: string;
+    /** 読める名前 (日本語・英語)。知らない符号はそのまま */
+    label: string;
+}
+/**
+ * 録画の字幕のうち、第2言語から後ろ (`CaptionPages.others`)。**第1言語は今までどおり `pages`** —
+ * 版 (`v`) を上げずに足したので、知らない受け側は第1言語だけを描く
+ */
+export interface CaptionLanguagePages extends CaptionLanguage {
+    pages: {
+        at: number;
+        page: CaptionPage;
+    }[];
+}
+/** 第何言語かと ISO 639 の符号から、画面に出す名前を付ける */
+export declare function captionLanguage(index: number, code: string): CaptionLanguage;
+/** `?language=` を読む (1〜8)。省いた・読めないときは第1言語 */
+export declare function parseCaptionLanguage(value: string | null): number;