@danything/arib 2.1.0 → 2.3.0

package/dist/mmt-media.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 4K の放送 (MMT/TLV) の映像・音声・字幕を取り出す (ISO/IEC 23008-1、ARIB STD-B60)。TS の `pes.ts` に当たる。
+ *
+ * MMT では、映像・音声・字幕は MPU (頭出しできる所から次の頭出しできる所まで) に分けて送られる。
+ * MPU の中身はアクセスユニット (映像の 1 コマ、音声の 1 フレーム) の並びで、データユニットを
+ * MMTP のパケットに分割したり、小さいものを 1 つに集約したりして運ぶ (`mmtp.ts` の `parseMpu`)。
+ *
+ * **時刻はパケットには無く、MPT の記述子にある。** MPU タイムスタンプ記述子が MPU の最初の提示時刻を、
+ * MPU 拡張タイムスタンプ記述子がアクセスユニットごとのずれを、これから来る MPU のぶんまで並べる
+ * (実機のケーブルの BS4K で確かめた。映像は 1 MPU に 32 コマ、音声は 4 フレーム)。
+ * 時刻は NTP の 64 ビットで来るので、ここで **90 kHz** に直す (TS の PTS と同じ物差し。一周はしない)。
+ *
+ * 中身の形式は次のとおり。実機の録りは映像・音声がスクランブルされていて中身を読めないので、どれも推定。
+ *
+ * - 映像 (`hev1`): データユニット 1 つが、長さ (4 バイト) を前に付けた NAL ユニット。MPU は ISO BMFF の形式なので、
+ *   サンプルの中身も MP4 と同じ形と見ている。同じ sample_number のデータユニットが 1 つのコマ
+ * - 音声 (`mp4a`): データユニット 1 つが LATM の AudioMuxElement (LOAS の同期のヘッダーは付かない)。
+ *   MPT の音声コンポーネント記述子の stream_type は 0x11 (LATM/LOAS) だった (確かめた)
+ * - 字幕 (`stpp`): MPU 1 つが TTML の文書 1 つ (`ttml.ts` で読む)。文書の中の画像 (PNG) は扱わない
+ *
+ * スクランブルされたパケットは数えて捨てる (`scrambled`)。復号はエージェントの仕事
+ */
+import { CLOCK } from "./pes.js";
+/** 放送の時刻の物差し (TS の PTS と同じ。`pes.ts` の `CLOCK`) */
+export { CLOCK };
+/** NTP の 64 ビットの時刻 (上位 32 ビットが秒、下位 32 ビットが端数) を 90 kHz に */
+export declare function ntpToClock(data: Uint8Array, at: number): number;
+/** MPU タイムスタンプ記述子を読む。`[mpu_sequence_number, 最初の提示時刻 (90 kHz)]` の並び */
+export declare function parseMpuTimestamps(body: Uint8Array): [number, number][];
+/** MPU 拡張タイムスタンプ記述子の、MPU 1 つぶん。時間は `timescale` の単位 */
+export interface MpuExtendedTimestamp {
+    mpuSequenceNumber: number;
+    timescale: number;
+    /** mpu_decoding_time_offset。最初のアクセスユニットの DTS が、最初の提示時刻より前にずれる長さ */
+    decodingOffset: number;
+    /** アクセスユニットごとの、DTS から PTS までのずれ (デコードの順) */
+    dtsPtsOffsets: number[];
+    /** アクセスユニットごとの、次のアクセスユニットの DTS までの長さ (pts_offset) */
+    durations: number[];
+}
+/**
+ * MPU 拡張タイムスタンプ記述子を読む。次のものは DTS を進められないので、空を返す (その MPU は時刻が分からないものとして捨てる)
+ *
+ * - timescale を持たないもの (MPU のメタデータの mdhd を見る、の意味)。放送ではメタデータを送らない
+ * - pts_offset を持たないもの (pts_offset_type 0)。コマの長さが分からない
+ */
+export declare function parseMpuExtendedTimestamps(body: Uint8Array): MpuExtendedTimestamp[];
+/** アクセスユニットの時刻 (90 kHz) */
+export interface UnitTime {
+    pts: number;
+    dts: number;
+    /** 次のアクセスユニットの DTS まで */
+    duration: number;
+}
+/**
+ * MPU の `index` 番目 (デコードの順、0 から) のアクセスユニットの時刻。
+ * DTS は最初の提示時刻から decodingOffset だけ戻った所に始まり、durations を足して進む。
+ * PTS は DTS に dtsPtsOffsets を足したもの。記述子に無い番目なら null
+ */
+export declare function unitTime(presentation: number, extended: MpuExtendedTimestamp, index: number): UnitTime | null;
+/** AAC の設定 (LATM の StreamMuxConfig にある AudioSpecificConfig) */
+export interface AacConfig {
+    /** AudioSpecificConfig のバイト列 (MP4 の esds にそのまま入れる) */
+    audioSpecificConfig: Uint8Array;
+    /** audioObjectType (2 は AAC LC) */
+    objectType: number;
+    sampleRate: number;
+    /** チャンネルの数 (channelConfiguration 7 は 8) */
+    channels: number;
+}
+/**
+ * LATM の AudioMuxElement (muxConfigPresent = 1) から、AAC のフレームを取り出す。
+ * **設定 (StreamMuxConfig) は来たときだけ書いてあり、あいだは「前と同じ」になる** ので、前の設定を覚えておく。
+ *
+ * 読むのは放送で使う形 (番組 1・層 1・サブフレーム 1・frameLengthType 0) だけ。ほかの形は null を返す
+ */
+export declare class LatmReader {
+    private config;
+    read(element: Uint8Array): {
+        config: AacConfig;
+        frame: Uint8Array;
+    } | null;
+    private readStreamMuxConfig;
+}
+export type MediaKind = "video" | "audio" | "caption";
+/** 取り出すアセット (MPT のアセットのうち、映像・音声・字幕のそれぞれ最初のもの) */
+export interface MediaAsset {
+    kind: MediaKind;
+    /** asset_type (`hev1`・`mp4a`・`stpp`) */
+    type: string;
+    packetId: number;
+    /** MH-ストリーム識別記述子の component_tag。無ければ null */
+    componentTag: number | null;
+}
+interface UnitBase extends UnitTime {
+    asset: MediaAsset;
+    mpuSequenceNumber: number;
+}
+/** 映像の 1 コマ */
+export interface VideoUnit extends UnitBase {
+    kind: "video";
+    /** NAL ユニットの並び (長さの前置きを外したもの) */
+    nals: Uint8Array[];
+    /** IRAP (IDR・CRA・BLA) のピクチャを含む */
+    keyframe: boolean;
+}
+/** 音声の 1 フレーム */
+export interface AudioUnit extends UnitBase {
+    kind: "audio";
+    /** AAC のフレーム (LATM を外したもの。ADTS のヘッダーも無い) */
+    frame: Uint8Array;
+    config: AacConfig;
+}
+/** 字幕の文書 1 つ。時刻は MPU の最初の提示時刻 */
+export interface CaptionUnit extends UnitBase {
+    kind: "caption";
+    /** TTML の文書 (UTF-8 を読んだもの) */
+    document: string;
+}
+export type MediaUnit = VideoUnit | AudioUnit | CaptionUnit;
+/**
+ * `MmtMediaReader.feed` が返すもの。選んだアセットが変わったら (番組が替わったときなど)、
+ * 先に `assets` が来る。受け側は組み立て中のもの (fMP4 の初期化セグメント) を作り直す
+ */
+export type MediaEvent = {
+    kind: "assets";
+    assets: MediaAsset[];
+} | MediaUnit;
+/**
+ * 1 局に絞った TLV のバイト列 (`mmt-service-filter.ts`) から、映像・音声・字幕のアクセスユニットを時刻つきで取り出す。
+ *
+ * - 局 (`serviceId` = MMT_package_id) の MPT を読んで、映像・音声・字幕のそれぞれ最初のアセットを選ぶ。
+ *   アセットは MPT と同じ IP の並びのもの (在りかの種類 0) だけを読む
+ * - 時刻は MPT の記述子から引く。時刻がまだ分からない MPU (最初の MPT より先に来たもの) は数えて捨てる (`untimed`)
+ * - パケットが欠けた (packet_sequence_number が続かない) アクセスユニットは捨てる (`dropped`)
+ * - アクセスユニットは、次のアクセスユニット (か次の MPU) の始まりが来たときに返す。最後のものは `end` で返す
+ */
+export declare class MmtMediaReader {
+    private readonly serviceId;
+    private readonly tlv;
+    private readonly ip;
+    private readonly signaling;
+    /** `並び/packet_id` → 組み立て */
+    private tracks;
+    /** 選んだアセットの並び (変わったかを見る) */
+    private selection;
+    /** 選んだアセットの MMTP のパケット (MPU) の数。スクランブルされていたもの (`scrambled`) も数える */
+    media: number;
+    /** スクランブルされていて読めなかった MMTP のパケットの数 */
+    scrambled: number;
+    /** 時刻が分からずに捨てたアクセスユニットの数 */
+    untimed: number;
+    /** パケットが欠けたか、中身を読めずに捨てたアクセスユニットの数 */
+    dropped: number;
+    constructor(serviceId: number);
+    /** 選んでいるアセット */
+    get assets(): MediaAsset[];
+    feed(chunk: Uint8Array): Generator<MediaEvent>;
+    /** 終わりまで読んだとき、組み立て中のアクセスユニットを閉じて返す (録画のファイルの最後など) */
+    end(): Generator<MediaUnit>;
+    /** MPT から、アセットを選び直して時刻を覚える */
+    private readMpt;
+    /** MPU のパケットの中身を 1 つ読む */
+    private readMpu;
+    /** データユニット (分割したものはその断片) を 1 つ受ける。ヘッダーは断片ごとに付いている */
+    private dataUnit;
+    private keep;
+    /** 組み立て中のアクセスユニットを閉じて返す */
+    private finish;
+}