From 8a13e844eed2c844765b7a20423979e69d03edd6 Mon Sep 17 00:00:00 2001
From: ForeverSc <fengshuochn@126.com>
Date: Tue, 4 Jun 2024 00:40:41 +0800
Subject: [PATCH] docs: update api docs

---
 README.md    | 53 ++++++++++++++++++++++++++++++++++++------
 README_CN.md | 65 +++++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 98 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 3a5b2b2..6b90ced 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,8 @@ npm install web-demuxer
 import { WebDemuxer } from "web-demuxer"
 
 const demuxer = new WebDemuxer({
-  // ⚠️ you need to put the dist/wasm-files file in the npm package into a static directory like public, making sure that the js and wasm in wasm-files are in the same directory
+  // ⚠️ you need to put the dist/wasm-files file in the npm package into a static directory like public
+  // making sure that the js and wasm in wasm-files are in the same directory
   wasmLoaderPath: "https://cdn.jsdelivr.net/npm/web-demuxer@latest/dist/wasm-files/ffmpeg.js",
 })
 
@@ -55,13 +56,51 @@ async function seek(time) {
 - [Play Video](https://foreversc.github.io/web-demuxer/#example-play) ｜ [code](https://github.com/ForeverSc/web-demuxer/blob/main/index.html#L123)
 
 ## API
-TODO: To be added, you can first look at the specific implementation in `src/web-demuxer.ts` with the `index.html` use case
+### `WebDemuxer`
+#### Constructor
+Creates a new instance of `WebDemuxer`.
 
-### `getVideoDecoderConfig`
-### `seekEncodedVideoChunk`
-### `readAVPacket`
-### `getAVStream`
-### `getAVPacket`
+##### Parameters
+- `options`: Required, configuration options
+  - `wasmLoaderPath`: Required, the address of the JS loader file corresponding to the wasm (corresponds to `dist/wasm-files/ffmpeg.js` or `dist/wasm-files/ffmpeg-mini.js` in the npm package)
+  > ⚠️ You need to ensure that the wasm and JS loader files are placed in the same accessible directory. The JS loader will request the wasm file in the same directory by default.
+
+#### `load(file: File): Promise<boolean>`
+Loads the file and waits for the wasm worker to load. You need to wait for the `load` method to succeed before calling subsequent methods.
+
+##### Parameters
+- `file: File`: Required, the `File` object to be processed
+
+#### `getVideoDecoderConfig(): Promise<VideoDecoderConfig>`
+Parses the video stream and obtains the `VideoDecoderConfig` of the file. The return value can be directly used as an input parameter for the `configure` method of `VideoDecoder`.
+
+#### `getAudioDecoderConfig(): Promise<AudioDecoderConfig>`
+Parses the audio stream and obtains the `AudioDecoderConfig` of the file. The return value can be directly used as an input parameter for the `configure` method of `AudioDecoder`.
+
+#### `seekEncodedVideoChunk(timestamp: number): Promise<EncodedVideoChunk>`
+Obtains the video data at the specified timestamp (defaults to the keyframe). The return value can be directly used as an input parameter for the `decode` method of `VideoDecoder`.
+
+##### Parameters
+- `timestamp: number`: Required, in seconds
+
+#### `seekEncodedAudioChunk(timestamp: number): Promise<EncodedAudioChunk>`
+Obtains the audio data at the specified timestamp. The return value can be directly used as an input parameter for the `decode` method of `AudioDecoder`.
+
+##### Parameters
+- `timestamp: number`: Required, in seconds
+
+#### `readAVPacket(start: number, end: number, streamType?: AVMediaType, streamIndex?: number): ReadableStream<WebAVPacket>`
+Returns a `ReadableStream` for streaming packet data.
+
+#### `getAVStream(streamType?: AVMediaType, streamIndex?: number): Promise<WebAVStream>`
+Obtains data from the specified stream in the file.
+
+#### `getAVPacket(timestamp: number, streamType?: AVMediaType, streamIndex?: number): Promise<WebAVPacket>`
+Obtains the data at the specified timestamp in the file.
+
+### Convenience API
+Semantic wrappers based on the basic API to simplify input parameters
+TODO
 
 ## Custom Demuxer
 TODO
diff --git a/README_CN.md b/README_CN.md
index 8389b2b..f7d6acd 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -2,25 +2,26 @@
 <h1 align="center">Web-Demuxer</h1>
 <p align="center">使用WebAssembly在浏览器中对媒体文件进行解封装, 专门为WebCodecs设计</p>
 
-## Purpose
+## 目的
 WebCodecs只提供了decode的能力，但没有提供demux的能力。有一些JS解封装mp4box.js很酷，但它只支持mp4，Web-Demuxer的目的是一次性支持更多媒体格式
 
-## Features
+## 特征
 - 🪄 专门为WebCodecs设计，API对于WebCodecs开发而言十分友好，可以轻松实现媒体文件的解封装
 - 📦 一次性支持多种媒体格式，比如mov/mp4/mkv/webm/flv/m4v/wmv/avi等等
 - 🧩 支持自定义打包，可以调整配置，打包出指定格式的demuxer
 
-## Install
+## 安装
 ```bash
 npm install web-demuxer
 ```
 
-## Usage
+## 使用
 ```typescript
 import { WebDemuxer } from "web-demuxer"
 
 const demuxer = new WebDemuxer({
-  // ⚠️ 你需要将npm包中dist/wasm-files文件放到类似public的静态目录下，保证wasm-files中的js和wasm在同一目录下
+  // ⚠️ 你需要将npm包中dist/wasm-files文件放到类似public的静态目录下
+  // 并确保wasm-files中的js和wasm文件在同一目录下
   wasmLoaderPath: "https://cdn.jsdelivr.net/npm/web-demuxer@latest/dist/wasm-files/ffmpeg.js",
 })
 
@@ -50,20 +51,58 @@ async function seek(time) {
 }
 ```
 
-## 案例
+## 样例
 - [Seek Video Frame](https://foreversc.github.io/web-demuxer/#example-seek) ｜ [code](https://github.com/ForeverSc/web-demuxer/blob/main/index.html#L96)
 - [Play Video](https://foreversc.github.io/web-demuxer/#example-play) ｜ [code](https://github.com/ForeverSc/web-demuxer/blob/main/index.html#L123)
 
 ## API
-TODO: 待补充，你可以先看`src/web-demuxer.ts`中的具体实现与`index.html`的使用案例
+### `WebDemuxer`
+#### 构造函数
+创建一个新的`WebDemuxer`实例
 
-### `getVideoDecoderConfig`
-### `seekEncodedVideoChunk`
-### `readAVPacket`
-### `getAVStream`
-### `getAVPacket`
+##### 参数
+- `options`: 必填, 配置选项
+  - `wasmLoaderPath`: 必填，wasm对应的js loader文件地址（对应npm包中`dist/wasm-files/ffmpeg.js`或`dist/wasm-files/ffmpeg-mini.js`）
+  > ⚠️ 你需要确保将wasm 和js loader文件放在同一个可访问目录下，js loader会默认去请求同目录下的wasm文件
 
-## Custom Demuxer
+#### `load(file: File): Promise<boolean>`
+加载文件并等待wasm worker加载完成。需要等待load方法执行成功后，才可以继续调用后续的方法
+
+##### 参数
+- `file: File`: 必填，需要处理的`File`对象
+
+#### `getVideoDecoderConfig(): Promise<VideoDecoderConfig>`
+解析视频流，获取文件的`VideoDecoderConfig`, 返回值可直接作为`VideoDecoder`的`configure`方法的入参
+
+#### `getAudioDecoderConfig(): Promise<AudioDecoderConfig>`
+解析音频流，获取文件的`AudioDecoderConfig`, 返回值可直接作为`AudioDecoder`的`configure`方法的入参
+
+#### `seekEncodedVideoChunk(timestamp: number): Promise<EncodedVideoChunk>`
+根据传入时间点，获取指定时间点的视频数据（默认取关键帧），返回值可直接作为`VideoDecoder`的`decode`方法的入参
+
+##### 参数
+- `timestamp: number`: 必填，单位为s
+
+#### `seekEncodedAudioChunk(timestamp: number): Promise<EncodedAudioChunk>`
+根据传入时间点，获取指定时间点的音频数据，返回值可直接作为`AudioDecoder`的`decode`方法的入参
+
+##### 参数
+- `timestamp: number`: 必填，单位为s
+
+#### `readAVPacket(start: number, end: number, streamType?: AVMediaType, streamIndex?: number): ReadableStream<WebAVPacket>`
+返回一个`ReadableStream`, 用于流式读取packet数据
+
+#### `getAVStream(streamType?: AVMediaType, streamIndex?: number): Promise<WebAVStream>`
+获取文件中指定stream的数据
+
+#### `getAVPacket(timestamp: number, streamType?: AVMediaType, streamIndex?: number): Promise<WebAVPacket>`
+获取文件中指定时间点的数据
+
+### 便利API
+基于基础API的语义化封装，简化入参
+TODO
+
+## 自定义Demuxer
 TODO
 
 ## License