docs: guide

bilibili · Dec 10, 2023 · 387f917 · 387f917
1 parent ec425a5
commit 387f917
Show file tree

Hide file tree

Showing 9 changed files with 70 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -85,6 +85,8 @@ This repo uses lerna + yarn to manage packages.
    2. 确定对应 DEMO 的 path，是 `packages/av-cliper/demo` 目录下的文件名，如 `concat-media.html`
    3. 在浏览器打开最终 URL：`http://localhost:6066/concat-media.html`
 
+若你有意贡献代码，建议先跟通过 Github Issue、Discussions、微信（`liujun_fenghen`）与作者讨论
+
 ---
 
 加微信 `liujun_fenghen` 备注 WebAV 邀请进入微信群

diff --git a/doc-site/.dumirc.ts b/doc-site/.dumirc.ts
@@ -7,7 +7,6 @@ export default defineConfig({
     socialLinks: {
       github: 'https://github.com/hughfenghen/WebAV'
     },
-    footer: 'Powered by <a href="https://github.com/hughfenghen/WebAV">WebAV</a>'
   },
   ...(process.env.NODE_ENV === 'development' ? {
     base: '/',

diff --git a/doc-site/docs/api/av-canvas.md b/doc-site/docs/api/av-canvas.md
diff --git a/doc-site/docs/api/av-cliper.md b/doc-site/docs/api/av-cliper.md
diff --git a/doc-site/docs/api/av-recorder.md b/doc-site/docs/api/av-recorder.md
diff --git a/doc-site/docs/article/index.md b/doc-site/docs/article/index.md
@@ -1,13 +1,14 @@
 ---
 nav:
-  title: 文章
+  title: Article
   order: 3
+sidebar: false
 ---
 
 # 相关文章索引
 
 - [WebCodecs 开启 Web 音视频新篇章](//hughfenghen.github.io/posts/2023/10/06/webcodecs-new-era-for-media-on-the-web/)
-  - LVS 分享主题，是后面系列文章的总结
+  - LVS (Live Video Stack) 分享主题，是后面系列文章的总结
 - [【译】WebCodecs 说明](https://hughfenghen.github.io/posts/2023/10/02/webcodecs-explainer/)
 - WebAV 系列
   - [Web 音视频（零）概览](//hughfenghen.github.io/posts/2023/07/16/webav-0-overview/)

diff --git a/doc-site/docs/guide/index.md b/doc-site/docs/guide/index.md
@@ -0,0 +1,53 @@
+---
+nav: Guide
+order: 1
+
+sidebar: false
+---
+
+# 指南
+
+开始前，建议先快速过一遍 [DEMO](../demo/1_1-decode-video.md)，了解 WebAV 能实现哪些能力；
+
+## 接入
+
+在 DEMO 下方有对应源码，添加依赖后复制 DEMO 源码，就能在项目中运行。
+
+```shell
+npm install @webav-cliper
+
+yarn add @webav-cliper
+```
+
+## 项目模块
+
+WebAV 项目包含三个模块，使用 TypeDoc 生成 API 文档
+
+- [@webav/av-cliper](//hughfenghen.github.io/WebAV/_api/av-cliper/)
+  - 提供音视频数据处理的基础 API
+  - 包括：音视频解码、合成、拼接、裁剪等功能等等
+- [@webav/av-recorder](//hughfenghen.github.io/WebAV/_api/av-recorder/)
+  - 录制 `MediaStream`，输出 MP4 视频
+  - 在浏览器中，可以中 canvas、video、摄像头、麦克风、分享屏幕等 API 获取 `MediaStream` 对象
+- [@webav/av-canvas](//hughfenghen.github.io/WebAV/_api/av-canvas/)
+  - 用户或代码可操作的“画布”，能添加、控制各种素材，支持输出 `MediaStream`
+  - 素材包括：摄像头、麦克风、屏幕、音视频文件、图片、文字
+  - 输出 `MediaStream` 意味着能将“画布”内容推流至服务器或录制为本地视频
+
+`@webav/av-cliper` 的 API 相对多一些，建议先阅读[基础概念](https://hughfenghen.github.io/WebAV/_api/av-cliper/#md:basic-concepts-%E5%9F%BA%E7%A1%80%E6%A6%82%E5%BF%B5)，有助于快速理解 DEMO 源码与其他 API
+
+## 贡献
+
+若你对 WebAV 感兴趣，可以尝试在本地启动项目
+
+1. 安装依赖：在根目录执行 `yarn install`
+2. 构建所有 packages：在根目录执行 `yarn build`
+3. 运行 DEMO
+   1. cd 到特定的 package 目录，比如 `cd packages/av-cliper`
+   2. 执行 `yarn dev`
+4. 访问 DEMO
+   1. 复制控制台中打印的 baseUrl，类似 `http://localhost:6066/`
+   2. 确定对应 DEMO 的 path，是 `packages/av-cliper/demo` 目录下的文件名，如 `concat-media.html`
+   3. 在浏览器打开最终 URL：`http://localhost:6066/concat-media.html`
+
+若你有意贡献代码，建议先通过 Github Issue、Discussions、微信（`liujun_fenghen`）与作者讨论
diff --git a/doc-site/docs/index.md b/doc-site/docs/index.md
@@ -4,8 +4,8 @@ hero:
   title: WebAV
   description: WebAV Doc Site
   actions:
-    - text: API (建设中...)
-      link: /api/av-canvas
+    - text: Guide
+      link: /guide/
     - text: DEMO
       link: /demo/1_1-decode-video
 ---
diff --git a/packages/av-cliper/README.md b/packages/av-cliper/README.md
@@ -6,19 +6,23 @@ WebCodecs-based, combine video, audio, images, text, with animation support
 ## Basic Concepts 基础概念
 
 - `Combinator`: add `OffscreenSprite`, output video stream
-  - Currently only supports outputting binary streams for MP4,AAC format
-- `OffscreenSprite`: wraps the resource (Clip), attaching Rect (position, width, height, animation) information to the resource so that it can be drawn to the Canvas
+  - Currently only supports outputting binary streams for MP4 format
 - `IClip`: Abstract encapsulation of resources, reading (`IClip.tick(time)`) raw data of resources by time slice, has been implemented for the `IClip` interface with:
   - `MP4Clip, AudioClip, ImgClip, EmbedSubtitlesClip` (embedded SRT subtitles), these are the types of resources supported by `Combinator`
+- `BaseSprite`: An abstract representation of manipulable elements, attaching Rect information (position, width, height, layer, animation) to resources to make them controllable.
+  - `OffscreenSprite`: Wraps resources (`IClip`) and adds them to a `Combinator` for background offscreen video synthesis.
+  - `AVCanvas`: Includes `VideoSprite, AudioSprite, ImgSprite, FontSprite` to support user or program control over the positioning of drawn resources.
 
 <hr />
 
 - `Combinator`： 视频合成器， add `OffscreenSprite`， output 视频流
-  - 目前仅支持输出 MP4,AAC 格式的二进制流
-- `OffscreenSprite`： 包装资源（Clip），给资源附加 Rect（位置、宽高、动画）信息，使得资源可被绘制到 Canvas 上
-- `IClip`： 资源的抽象封装，按时间片段读取（`IClip.tick(time)`）资源的原始数据，已实现 `IClip` 接口的有：
+  - 目前仅支持输出 MP4 格式的二进制流
+- `IClip`： 资源的抽象封装，按时间片段读取（`IClip.tick(time)`）资源的原始数据，`IClip` 接口的实现类有：
   - `MP4Clip, AudioClip, ImgClip, EmbedSubtitlesClip`（内嵌 SRT 字幕），这些是合成视频所支持的资源类型
+- `BaseSprite` 可操作元素的抽象，给资源附加 Rect（位置、宽高、层级、动画）信息，使得资源可被控制
+  - `OffscreenSprite`： 包装资源（`IClip`）添加到 `Combinator`，在后台离屏合成视频
+  - `AVCanvas` 包含了 `VideoSprite, AudioSprite, ImgSprite, FontSprite`，以支持用户或程序控制资源绘制的位置
 
-## Demo
+## DEMO
 
 <https://hughfenghen.github.io/WebAV/demo/1_1-decode-video>