pr-player 0.4.1 → 0.5.1

package/README.md

@@ -1,4 +1,4 @@
-# 对 flv 格式的地址进行解析 并输出 MediaStream，提供 demuxer 层(info、chunk、sei)回调、 decoder 层(audio、video)回调 ，提供 cut 等相关能力，以支持根据业务层 SEI 对视频进行剪切渲染。
+# 对 flv、hls、dash、mp4 格式的地址进行解析 并输出 MediaStream，提供 demuxer 层(info、chunk)回调、 decoder 层(audio、video、sei)回调 ，提供 cut 等相关能力，以支持根据业务层 SEI 对视频进行剪切渲染。
 
 ## 立即开始
 
@@ -14,16 +14,13 @@ npm i pr-player
 import { PrPlayer } from 'pr-player'
 
 // 除此之外 如果你需要自定义扩展 为你提供了独立的 Demuxer、Decoder、Render
-import { DemuxerWorker } from '../../src/index'
-import { DecoderWorker } from '../../src/index'
-import { RenderWorker } from '../../src/index'
+import { DemuxerWorker, DecoderWorker, RenderWorker } from 'pr-player'
 ```
 
 ## 快速使用
 
 ```js
 const player = new PrPlayer()
-const player = new PrPlayer({ debug: true })
 
 // 如果你只需要复解器相关的能力 可以拿到复解后的所有回调
 {
@@ -42,6 +39,7 @@ const player = new PrPlayer({ debug: true })
   }
   player.on.decoder.video = (video) => {
     console.log('\x1b[38;2;0;151;255m%c%s\x1b[0m', 'color:#0097ff;', `------->Breathe: video`, video)
+    // video.frame 为 VideoFrame，使用后需要 video.frame.close()
   }
   player.on.decoder.sei = (sei) => {
     console.log('\x1b[38;2;0;151;255m%c%s\x1b[0m', 'color:#0097ff;', `------->Breathe: sei`, sei)
@@ -51,6 +49,11 @@ const player = new PrPlayer({ debug: true })
 await player.start('https://sf1-cdn-tos.huoshanstatic.com/obj/media-fe/xgplayer_doc_video/flv/xgplayer-demo-720p.flv')
 player.setMute(false) // 默认都是静音 所以主动开启
 const stream = player.getStream()
+
+// 绑定到 video 标签
+const view = document.createElement('video')
+view.srcObject = stream
+view.play()
 ```
 
 ### 暂停渲染
@@ -72,10 +75,18 @@ player.stop()
 ### 创建剪切
 
 ```js
+// sx、sy、sw、sh 为原视频坐标系下的裁剪区域，通常配合 on.demuxer.info 中的 width、height 使用
+const { width, height } = info
 player.cut.create('cut-any-key', { sx: width * 0.25, sy: height * 0.4, sw: width * 0.5, sh: height * 0.5 })
 const stream = player.cut.getStream('cut-any-key')
 ```
 
+### 修改剪切区域
+
+```js
+player.cut.setCut('cut-any-key', { sx: 100, sy: 100, sw: 640, sh: 360 })
+```
+
 ### 暂停剪切
 
 ```js
@@ -88,6 +99,138 @@ player.cut.setPause('cut-any-key', true)
 player.cut.remove('cut-any-key')
 ```
 
+## 结合 SEI 进行剪切
+
+- 典型流程：解析 SEI 拿到业务坐标 → 创建或更新 cut → 输出独立 MediaStream
+
+```js
+let videoInfo
+
+player.on.demuxer.info = (info) => {
+  videoInfo = info
+}
+
+player.on.decoder.sei = (sei) => {
+  // 根据业务协议解析 sei，得到裁剪区域
+  const { sx, sy, sw, sh } = parseSeiRect(sei, videoInfo)
+
+  if (!player.cut.getStream('sei-cut')) {
+    player.cut.create('sei-cut', { sx, sy, sw, sh })
+  } else {
+    player.cut.setCut('sei-cut', { sx, sy, sw, sh })
+  }
+}
+
+await player.start(url)
+const cutStream = player.cut.getStream('sei-cut')
+```
+
+## PrPlayer API
+
+### 构造
+
+```js
+new PrPlayer({ frameTrack?: boolean })
+```
+
+- `frameTrack`：是否默认开启追帧，适用于直播场景
+
+### 实例方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `start(url)` | 开始拉流并解析，第一帧视频到达后 resolve |
+| `stop()` | 停止拉流，销毁 worker 与 MediaStream |
+| `getStream()` | 获取主路视频 MediaStream |
+| `setPause(pause)` | 暂停/恢复主路渲染 |
+| `setMute(state?)` | 设置静音，默认静音，播放前通常需 `setMute(false)` |
+| `setOutputGain(gain)` | 设置输出音量 |
+| `setFrameTrack(frameTrack)` | 开启/关闭追帧，适用于直播场景 |
+| `isReady()` | 返回 Promise，MediaStream 激活后 resolve |
+
+### cut 命名空间
+
+| 方法 | 说明 |
+| --- | --- |
+| `cut.create(key, { sx, sy, sw, sh })` | 创建剪切路，返回 cut 的 MediaStream |
+| `cut.getStream(key)` | 获取已创建的 cut MediaStream |
+| `cut.setCut(key, cutOption)` | 运行时修改裁剪区域 |
+| `cut.setPause(key, pause)` | 暂停/恢复指定 cut 路 |
+| `cut.remove(key)` | 移除指定 cut 路 |
+
+### 实例属性
+
+- `player.on`：事件回调，见下方
+- `player.audioPlayer`：内部音频播放器，可通过 `player.audioPlayer.getStream()` 获取音频 MediaStream
+
+## 事件回调 player.on
+
+### demuxer
+
+```js
+player.on.demuxer.info = (info) => {}    // 流元信息，如 width、height
+player.on.demuxer.config = (config) => {} // 音视频 decoder 配置
+player.on.demuxer.chunk = (chunk) => {}  // 解复用后的 chunk
+```
+
+### decoder
+
+```js
+player.on.decoder.audio = ({ audioData, playbackRate }) => {}
+player.on.decoder.video = ({ timestamp, frame }) => {} // frame 为 VideoFrame
+player.on.decoder.sei = (payload) => {}                // H.264 SEI 载荷
+player.on.decoder.analysis = ({ fps, cacheLength, decodingSpeed, decodingSpeedRatio }) => {}
+```
+
+### 其他
+
+```js
+player.on.error = (e) => {}
+```
+
+## 支持的地址格式
+
+- `flv`：HTTP-FLV 直播/点播
+- `hls`：`.m3u8` 直播/点播（TS 容器 + H.264/AAC）
+- `dash`：`.mpd` DASH 点播/直播（fMP4 分片 + H.264/AAC）
+- `mp4`：渐进式 MP4 点播（H.264/AAC）
+
+```js
+// flv
+await player.start('https://example.com/live.flv')
+
+// hls
+await player.start('https://example.com/live.m3u8')
+
+// dash
+await player.start('https://example.com/manifest.mpd')
+
+// mp4
+await player.start('https://example.com/video.mp4')
+```
+
+- 直播场景可配合 `setFrameTrack(true)` 自动追帧
+- hls / dash / mp4 点播会自动关闭追帧
+- `rtmp://` 地址浏览器内不支持，请使用 HTTP-FLV 或 HLS 替代
+
+## 自定义扩展
+
+- 如果你不需要完整的 PrPlayer，可以单独使用 Worker 层自行组装管线：
+
+```js
+import { DemuxerWorker, DecoderWorker, RenderWorker } from 'pr-player'
+
+const demuxerWorker = new DemuxerWorker()
+const decoderWorker = new DecoderWorker()
+const renderWorker = new RenderWorker()
+```
+
+## 浏览器要求
+
+- 需支持 WebCodecs（`VideoDecoder` / `AudioDecoder`）
+- 视频输出优先使用 `MediaStreamTrackGenerator`，不支持时自动降级为 `canvas.captureStream()`
+- 剪切多路输出需浏览器支持 `VideoFrame` 的 `visibleRect` 裁剪
+
 ## 代码仓库
 
 [github](https://github.com/breathe97/pr-player)

package/dist/{src/PrPlayer.d.ts → PrPlayer.d.ts}

@@ -12,16 +12,14 @@ interface On {
         }) => void;
         video?: (_frame: {
             timestamp: number;
-            bitmap: ImageBitmap;
+            frame: VideoFrame;
         }) => void;
         sei?: (_payload: Uint8Array) => void;
         analysis?: (_e: any) => void;
     };
-    debug?: (_e: any) => void;
     error?: (_e: any) => void;
 }
 interface PrPlayerOption {
-    debug?: boolean;
     frameTrack?: boolean;
 }
 export declare class PrPlayer {
@@ -129,5 +127,7 @@ export declare class PrPlayer {
     private initRender;
     private flv;
     private hls;
+    private mp4;
+    private dash;
 }
 export {};

package/dist/{src/decoder → decoder}/Decoder.d.ts

@@ -27,7 +27,7 @@ export declare class Decoder {
     on: On;
     constructor();
     init: (pattern: Pattern) => void;
-    initAudio: (config: AudioDecoderConfig) => void;
+    initAudio: (config: AudioDecoderConfig) => Promise<void>;
     initVideo: (config: VideoDecoderConfig) => void;
     setFrameTrack: (frameTrack: boolean) => void;
     push: (chunk: PendingChunk) => void;

package/dist/{src/decoder → decoder}/type.d.ts

@@ -8,7 +8,7 @@ export interface On {
     };
     video: {
         decode?: (_frame: {
-            bitmap: ImageBitmap;
+            frame: VideoFrame;
             timestamp: number;
         }) => void;
         error?: (_e: DOMException) => void;

package/dist/{src/demuxer → demuxer}/Cacher.d.ts

@@ -14,5 +14,6 @@ export declare class Cacher {
     push: (payload: Uint8Array) => void;
     next: (offset?: number) => false | DataView<ArrayBuffer>;
     pushChunk: (chunk: any) => void;
+    discardPayload: () => void;
     destroy: () => void;
 }

package/dist/{src/demuxer → demuxer}/Demuxer.d.ts

@@ -1,22 +1,9 @@
 import { Cacher, Chunk } from './Cacher';
 import { Pattern } from '../type';
-export interface AudioConfig {
-    kind: 'audio';
-    codec: string;
-    sampleRate: number;
-    numberOfChannels: number;
-}
-export interface VideoConfig {
-    kind: 'video';
-    codec: string;
-    sps: Uint8Array;
-    pps: Uint8Array;
-    description: Uint8Array;
-}
+export type { AudioConfig, VideoConfig } from './parsers/types';
 export interface On {
-    debug?: (_debug: unknown) => void;
     info?: (_info: any) => void;
-    config?: (_config: AudioConfig | VideoConfig) => void;
+    config?: (_config: import('./parsers/types').AudioConfig | import('./parsers/types').VideoConfig) => void;
     chunk?: (_chunk: Chunk) => void;
     sei?: (_sei: Uint8Array[]) => void;
 }

package/dist/{src/demuxer → demuxer/parsers}/264Parser.d.ts

@@ -5,13 +5,8 @@ export declare const parseAVCC: (avcc: Uint8Array) => {
     profile: number;
     compatibility: number;
     level: number;
-    lengthSizeMinusOne: number;
-    numOfSequenceParameterSets: number;
-    sequenceParameterSetLength: number;
-    sps: Uint8Array<ArrayBuffer | SharedArrayBuffer>;
-    numOfPictureParameterSets: number;
-    pictureParameterSetLength: number;
-    pps: Uint8Array<ArrayBuffer | SharedArrayBuffer>;
+    sps: Uint8Array<ArrayBufferLike>;
+    pps: Uint8Array<ArrayBufferLike>;
 };
 export declare const naluToAVCC: (nalu: Uint8Array) => Uint8Array;
 export declare const mergeNalus: (nalus: Uint8Array[]) => Uint8Array;
@@ -22,5 +17,5 @@ export declare const parseNalu: (nalu: Uint8Array) => {
         nal_ref_idc: number;
         nal_unit_type: number;
     };
-    data: Uint8Array<ArrayBuffer | SharedArrayBuffer>;
+    data: Uint8Array<ArrayBufferLike>;
 };

package/dist/demuxer/parsers/boxParser.d.ts

@@ -0,0 +1,19 @@
+export interface BoxInfo {
+    offset: number;
+    size: number;
+    type: string;
+    headerSize: number;
+    contentStart: number;
+}
+export declare const readBoxType: (view: DataView, offset: number) => string;
+export declare const readBoxAt: (view: DataView, offset: number, end: number) => BoxInfo | null;
+export declare const forEachBox: (view: DataView, start: number, end: number, fn: (box: BoxInfo) => void) => void;
+export declare const findBox: (view: DataView, start: number, end: number, type: string) => BoxInfo | null;
+export declare const collectBoxes: (view: DataView, start: number, end: number, type: string, out?: BoxInfo[]) => BoxInfo[];
+export declare const findBoxInRange: (view: DataView, start: number, end: number, type: string) => BoxInfo | null;
+export declare const findSampleEntryChild: (view: DataView, entryStart: number, entryEnd: number, type: string, skipBytes?: number) => BoxInfo | null;
+export declare const listTopLevelBoxes: (view: DataView, end: number, limit?: number) => {
+    type: string;
+    offset: number;
+    size: number;
+}[];

package/dist/{src/demuxer → demuxer/parsers}/flv264Parser.d.ts

@@ -1,7 +1,6 @@
-import { Chunk } from './Cacher';
-import { AudioConfig, VideoConfig } from './Demuxer';
-export interface On {
-    debug?: (_debug: any) => void;
+import { Chunk } from '../Cacher';
+import { AudioConfig, VideoConfig } from './types';
+interface On {
     info?: (_info: any) => void;
     config?: (_config: AudioConfig | VideoConfig) => void;
     chunk?: (_chunk: Chunk) => void;
@@ -25,3 +24,4 @@ export declare class ParseFLV {
     private getAMFName;
     private getAMFValue;
 }
+export {};

package/dist/demuxer/parsers/fmp4Parser.d.ts

@@ -0,0 +1,38 @@
+import { Chunk } from '../Cacher';
+import { AudioConfig, VideoConfig } from './types';
+interface On {
+    info?: (_info: any) => void;
+    config?: (_config: AudioConfig | VideoConfig) => void;
+    chunk?: (_chunk: Chunk) => void;
+}
+export declare class ParseFMP4 {
+    audioConfig?: AudioConfig;
+    videoConfig?: VideoConfig;
+    private tracks;
+    private mdatBox;
+    private progressiveParsed;
+    on: On;
+    /** moov-at-end 的 MP4 在 sample 提取完成前不能丢弃 buffer */
+    getDiscardOffset: (bufferLength: number, view: DataView) => number;
+    constructor();
+    parse: (view: DataView) => Promise<number>;
+    private tryRunProgressive;
+    private isProgressiveReady;
+    private parseMoov;
+    private readTkhdSize;
+    /** VisualSampleEntry 中的宽高（uint16，比 tkhd 更可靠） */
+    private readSampleEntrySize;
+    private parseTrak;
+    private parseEsds;
+    private findMdatForMoof;
+    private parseMoof;
+    private ticksToMs;
+    /** ctts：每个 sample 的 composition offset（timescale 单位） */
+    private readCttsOffsets;
+    private parseTraf;
+    private parseProgressive;
+    private collectProgressiveTrackSamples;
+    private isAvccKeyFrame;
+    private splitAvccNalus;
+}
+export {};

package/dist/demuxer/parsers/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './264Parser';
+export * from './boxParser';
+export * from './flv264Parser';
+export * from './ts264Parser';
+export * from './fmp4Parser';
+export * from './mpdParser';

package/dist/demuxer/parsers/mpdParser.d.ts

@@ -0,0 +1,41 @@
+export interface MpdByteRange {
+    start: number;
+    end: number;
+}
+export interface MpdSegmentTemplate {
+    initialization?: string;
+    media?: string;
+    timescale: number;
+    duration: number;
+    startNumber: number;
+}
+export interface MpdSegmentListInfo {
+    timescale: number;
+    duration: number;
+    initRange?: MpdByteRange;
+    segments: MpdByteRange[];
+}
+export interface MpdRepresentation {
+    id: string;
+    codecs: string;
+    bandwidth: number;
+    width?: number;
+    height?: number;
+    baseUrl?: string;
+    template?: MpdSegmentTemplate;
+    segmentList?: MpdSegmentListInfo;
+}
+export interface MpdAdaptation {
+    kind: 'video' | 'audio' | 'mux';
+    mimeType: string;
+    representation: MpdRepresentation;
+}
+export interface MpdInfo {
+    isLive: boolean;
+    duration?: number;
+    baseUrl: string;
+    adaptations: MpdAdaptation[];
+}
+export declare const resolveUrl: (baseUrl: string, href: string) => string;
+export declare const buildSegmentUrl: (baseUrl: string, template: string, vars: Record<string, string | number>) => string;
+export declare const parseMpd: (xml: string, mpdUrl: string) => MpdInfo;

package/dist/{src/demuxer → demuxer/parsers}/ts264Parser.d.ts

@@ -1,6 +1,6 @@
-import { Chunk } from './Cacher';
-import { AudioConfig, VideoConfig } from './Demuxer';
-export interface Pat {
+import { Chunk } from '../Cacher';
+import { AudioConfig, VideoConfig } from './types';
+interface Pat {
     header: {
         pointer_field: number;
         table_id: number;
@@ -45,7 +45,6 @@ export interface PESPacket {
     data: Uint8Array;
 }
 export interface On {
-    debug?: (_debug: any) => void;
     info?: (_info: any) => void;
     config?: (_config: AudioConfig | VideoConfig) => void;
     chunk?: (_chunk: Chunk) => void;
@@ -65,6 +64,8 @@ export declare class ParseTS {
     private parsePMT;
     private parseAdaptationField;
     private parseAudio;
+    /** 解析 ADTS 头，返回 header 长度与 AAC 配置 */
+    private parseAdts;
     private parseVideo;
     /**
      * 解析 PTS/DTS 时间戳（33-bit，单位：90kHz）
@@ -74,4 +75,7 @@ export declare class ParseTS {
         type: number;
         nalu: Uint8Array<ArrayBufferLike>;
     }[];
+    /** 查找 Annex-B 起始码，支持 0x000001 与 0x00000001 */
+    private findAnnexBStart;
 }
+export {};

package/dist/demuxer/parsers/types.d.ts

@@ -0,0 +1,14 @@
+export interface AudioConfig {
+    kind: 'audio';
+    codec: string;
+    sampleRate: number;
+    numberOfChannels: number;
+    description?: Uint8Array;
+}
+export interface VideoConfig {
+    kind: 'video';
+    codec: string;
+    sps: Uint8Array;
+    pps: Uint8Array;
+    description: Uint8Array;
+}

package/dist/{src/index.d.ts → index.d.ts}

@@ -5,3 +5,4 @@ export * from './render/Render';
 export * from './demuxer/DemuxerWorker';
 export * from './decoder/DecoderWorker';
 export * from './render/RenderWorker';
+export * from './demuxer/parsers/mpdParser';