From c3564f7223cc86b95bd26022feca66c4b4f0fb0e Mon Sep 17 00:00:00 2001 From: Sakiko Date: Thu, 6 Aug 2026 16:29:45 +0800 Subject: [PATCH] docs: align platform and C API documentation --- CODE_OF_CONDUCT.md | 7 +++++++ README.md | 3 ++- SECURITY.md | 7 +++++++ SUPPORT.md | 7 +++++++ docs/architecture.ja.md | 2 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/capi_reference.ja.md | 11 +++++++---- docs/capi_reference.md | 13 ++++++++----- docs/capi_reference.zh.md | 11 +++++++---- docs/integration.ja.md | 4 +++- docs/integration.md | 5 ++++- docs/platform_matrix.zh.md | 24 ++++++++++++++++++++++++ docs/releasing.ja.md | 14 ++++++++++++++ docs/releasing.md | 15 +++++++++++++++ docs/releasing.zh.md | 19 +++++++++++++++++++ readme/README.en.md | 4 ++-- readme/README.ja.md | 2 +- 18 files changed, 130 insertions(+), 22 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 docs/platform_matrix.zh.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..333693d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,7 @@ +# Code of Conduct + +Erika welcomes respectful, technical collaboration across Rust, C/C++, Flutter, platform-native, and media-engineering communities. Discuss code and evidence, not people. + +Harassment, discrimination, disclosure of personal data or credentials, and deliberate disruption are not acceptable. Maintainers may remove content or limit participation when needed to protect contributors and users. + +Use [SECURITY.md](SECURITY.md) for private security reporting and the repository issue tracker for ordinary bugs and feature discussions. diff --git a/README.md b/README.md index 65bea6a..0fe0eda 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ - **字幕** — SRT / WebVTT / ASS 解析，libass 渲染 (静态链接)，嵌入与外挂字幕轨 - **弹幕** — Bilibili XML / JSON 解析，DFM+ 碰撞避让布局引擎，glyph atlas 原生 GPU 渲染 - **播放引擎** — play / pause / stop / seek / 倍速，音频主时钟同步，vsync 量化调度 -- **C ABI** — 79 个导出函数，opaque handle 设计，可从 C / C++ / Swift / Dart FFI / 任何 FFI 语言调用 +- **C ABI** — opaque handle 设计，可从 C / C++ / Swift / Dart FFI / 任何 FFI 语言调用；以 `erika.h` 中的导出声明为准 - **Flutter 插件** — macOS + iOS + tvOS + Windows + Android + HarmonyOS 原生视图/Texture 嵌入 - **wgpu 后端** — Android 播放、overlay、截图与 Vulkan/GLES 恢复路径可用；HarmonyOS 走 Vulkan，用 OHNativeWindow 呈现、OHNativeBuffer 零拷贝导入；Linux 仍在规划中 @@ -112,6 +112,7 @@ docs/ 架构与嵌入文档 - [原生接入指南](docs/integration.zh.md) — C/C++/Win32/Swift 等非 Flutter 宿主的端到端嵌入 - [构建与依赖指南](docs/building.zh.md) — xtask、native 依赖、交叉编译 - [Flutter 嵌入](docs/flutter_embedding.zh.md) ・ [弹幕架构](docs/danmaku_architecture.md) +- [平台能力矩阵](docs/platform_matrix.zh.md) — 区分可编译、CI 覆盖、真机验收与预编译发布 - [发布与预编译产物](docs/releasing.md) — 各平台预编译 `erika_capi` 库下载与打包(英文) - [贡献 / 开发者指南](CONTRIBUTING.zh.md) — 仓库布局、线程模型、新增平台后端 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f1053b5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,7 @@ +# Security Policy + +Please report vulnerabilities through GitHub Security Advisories or a private maintainer channel. Do not publish credentials, real media-server URLs, private video samples, or exploit details in public issues. + +Reports should include the affected tag/commit, platform and target triple, a minimal reproduction, impact, and whether the issue involves the C ABI, prebuilt archives, native build scripts, Flutter glue, or network media handling. + +Security fixes are prioritized for maintained release tags and the default branch. Locally rebuilt forks, unpinned prebuilt archives, and platform-preview paths may require separate validation. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..6e4bc67 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,7 @@ +# Support + +For integration help, start with the architecture, build, C ABI, Flutter embedding, and platform-matrix documents under `docs/`. + +When filing a bug, include the Erika tag/commit, host platform, Rust target triple, renderer, media container/codecs, whether a prebuilt archive or source build was used, and a minimal reproduction. Remove credentials and private URLs from logs. + +For NipaPlay integration issues, also include the NipaPlay commit and `ERIKA_PREBUILT_TAG` or dependency pin. diff --git a/docs/architecture.ja.md b/docs/architecture.ja.md index a4387f2..4b626e4 100644 --- a/docs/architecture.ja.md +++ b/docs/architecture.ja.md @@ -19,7 +19,7 @@ Rust Player Core D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows) wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan presenter runtime ──── ties player + renderer + audio + overlays - C ABI ──────────────── 79 exported functions, two handle families + C ABI ──────────────── versioned public header、2 つの handle ファミリー Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding ``` diff --git a/docs/architecture.md b/docs/architecture.md index ead60b6..c366b5e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -22,7 +22,7 @@ Rust Player Core D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows) wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan presenter runtime ──── ties player + renderer + audio + overlays - C ABI ──────────────── 79 exported functions, two handle families + C ABI ──────────────── versioned public header, two handle families Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding ``` diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index c91b483..13e7404 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -19,7 +19,7 @@ Rust Player Core D3D11 renderer ─────── zero-copy D3D11VA, HDR10, subtitle/danmaku pass (Windows) wgpu renderer ──────── cross-platform video, overlays, capture, Android scRGB, OHOS Vulkan presenter runtime ──── ties player + renderer + audio + overlays - C ABI ──────────────── 79 exported functions, two handle families + C ABI ──────────────── 版本化公开头文件，两组 handle 接口族 Flutter plugin ─────── macOS + iOS + tvOS + Windows + Android + OpenHarmony embedding ``` diff --git a/docs/capi_reference.ja.md b/docs/capi_reference.ja.md index 894a302..d7b7e4e 100644 --- a/docs/capi_reference.ja.md +++ b/docs/capi_reference.ja.md @@ -22,9 +22,12 @@ Erika は独立した 2 つのエントリーポイントを公開します。 | `ErikaPresenterHandle` | **プッシュ** | Erika | native surface を Erika に渡し、表示フレームごとに `render_tick` を 1 回呼ぶ。Erika が decode・timing・audio・overlay・presentation を所有する。 | `ErikaPresenterHandle` が推奨パスで、Flutter plugin と native demo もこれを使います。 -コンパイルされるのは **macOS / iOS / tvOS / Windows / Android**。他のターゲットでは -`erika_presenter_create` は export されますが `NULL` を返し、presenter ファミリーの -残りは存在しません——presenter の利用はプラットフォームでガードしてください。 +コンパイルされるのは **macOS / iOS / tvOS / Windows / Android / HarmonyOS**。surface attach は +platform ごとに異なり、Apple は Metal、Windows は HWND/D3D11、Android/HarmonyOS は +wgpu/Vulkan surface を使います。HarmonyOS Flutter bridge は ArkTS platform channel が +構造化値を serialize して渡すため、presenter の JSON helper を使います。未対応 target では +`erika_presenter_create` が export されても `NULL` を返す場合があるため、platform guard と +create 成功の両方を確認してください。 2 つのファミリーは状態を共有しません。1 プロセスで両方使えますが、1 つのメディア セッションは正確に 1 つの handle に属します。 @@ -206,7 +209,7 @@ capabilities を渡すため Android extended-linear output は active になり ## `ErikaPresenterHandle` —— プッシュモデル Erika がフルスタックを所有し、ホストは surface を提供して `render_tick` を呼びます。 -**macOS / iOS / tvOS / Windows / Android。** +**macOS / iOS / tvOS / Windows / Android / HarmonyOS。** ### ライフサイクルと設定 diff --git a/docs/capi_reference.md b/docs/capi_reference.md index 8f51339..0a514a9 100644 --- a/docs/capi_reference.md +++ b/docs/capi_reference.md @@ -22,10 +22,13 @@ Erika exposes two independent entry points. Pick one per integration. | `ErikaPresenterHandle` | **Push** | Erika | You give Erika a native surface and call `render_tick` once per display frame. Erika owns decode, timing, audio, overlays, and presentation. | `ErikaPresenterHandle` is the recommended path and what the Flutter plugin and -the native demos use. It is compiled on **macOS, iOS, tvOS, Windows, and Android**. -On other targets `erika_presenter_create` is still exported but returns `NULL`, -and the rest of the presenter family is absent — guard presenter usage by -platform. +the native demos use. It is compiled on **macOS, iOS, tvOS, Windows, Android, +and HarmonyOS**. Surface attachment is platform-specific: Apple uses Metal, +Windows uses HWND/D3D11, and Android/HarmonyOS use wgpu/Vulkan surfaces. The +HarmonyOS Flutter bridge uses the JSON presenter helpers because ArkTS platform +channels already exchange structured serialized values. On unsupported targets +`erika_presenter_create` may be exported but returns `NULL`; guard presenter +usage by platform and by a successful create call. The two families do not share state; a process may use both, but a given media session lives in exactly one handle. @@ -225,7 +228,7 @@ capabilities and therefore cannot activate Android extended-linear output. ## `ErikaPresenterHandle` — push model Erika owns the full stack; the host supplies a surface and calls `render_tick`. -**macOS / iOS / tvOS / Windows / Android.** +**macOS / iOS / tvOS / Windows / Android / HarmonyOS.** ### Lifecycle and configuration diff --git a/docs/capi_reference.zh.md b/docs/capi_reference.zh.md index 56c2da0..ecab6d0 100644 --- a/docs/capi_reference.zh.md +++ b/docs/capi_reference.zh.md @@ -19,9 +19,12 @@ Erika 暴露两个相互独立的入口，每个集成选其一。 | `ErikaHandle` | **拉取（Pull）** | 宿主 | 你拥有渲染循环、自己拉取解码帧 / 驱动自己的合成器。 | | `ErikaPresenterHandle` | **推送（Push）** | Erika | 你把一个原生 surface 交给 Erika，每个显示帧调一次 `render_tick`。Erika 负责解码、时序、音频、overlay 和呈现。 | -`ErikaPresenterHandle` 是推荐路径，也是 Flutter 插件和原生 demo 所用的。它只在 -**macOS、iOS、tvOS、Windows、Android** 上编译。其它平台上 `erika_presenter_create` 仍然 -导出但返回 `NULL`，presenter 族的其余函数不存在——请按平台守卫 presenter 用法。 +`ErikaPresenterHandle` 是推荐路径，也是 Flutter 插件和原生 demo 所用的。它在 +**macOS、iOS、tvOS、Windows、Android、HarmonyOS** 上编译。surface attach 按平台不同： +Apple 使用 Metal，Windows 使用 HWND/D3D11，Android/HarmonyOS 使用 wgpu/Vulkan surface。 +HarmonyOS Flutter bridge 因 ArkTS 平台通道本身传递序列化结构化值，使用 presenter 的 JSON +辅助入口。其它不支持的平台上 `erika_presenter_create` 可能仍导出但返回 `NULL`；请同时按平台 +守卫 presenter 用法，并检查 create 是否成功。 两个族不共享状态；一个进程可同时使用两者，但单个媒体会话只活在一个 handle 里。 @@ -204,7 +207,7 @@ Android extended-linear 输出。 ## `ErikaPresenterHandle` —— 推送模型 Erika 拥有完整栈；宿主提供 surface 并调用 `render_tick`。 -**macOS / iOS / tvOS / Windows / Android。** +**macOS / iOS / tvOS / Windows / Android / HarmonyOS。** ### 生命周期与配置 diff --git a/docs/integration.ja.md b/docs/integration.ja.md index 08c5dd4..917dce3 100644 --- a/docs/integration.ja.md +++ b/docs/integration.ja.md @@ -23,7 +23,9 @@ Rust の `PresenterRuntime` を直接駆動します。以下の C ABI 呼び出 `ErikaHandle` は、独自コンポジタを持ち Erika の decode/timing/state だけが欲しいホスト 向けです。本ガイドの残りは presenter ベースです。 -presenter ファミリーは **macOS / iOS / tvOS / Windows / Android** でコンパイルされます。 +presenter ファミリーは **macOS / iOS / tvOS / Windows / Android / HarmonyOS** でコンパイルされます。 +native host API は platform ごとに異なります。HarmonyOS Flutter host は desktop sample を +そのまま再現するのではなく、通常 plugin の ArkTS JSON bridge を使います。 ## 2. ライフサイクル diff --git a/docs/integration.md b/docs/integration.md index ba84301..b890cb0 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -24,7 +24,10 @@ Use `ErikaPresenterHandle` unless you have a reason to render yourself. The pull-model `ErikaHandle` is for hosts that own their compositor and only want Erika's decode/timing/state. The rest of this guide is presenter-based. -The presenter family is compiled on **macOS, iOS, tvOS, Windows, and Android**. +The presenter family is compiled on **macOS, iOS, tvOS, Windows, Android, and +HarmonyOS**. The native host API is platform-specific; HarmonyOS Flutter hosts +normally use the plugin's ArkTS JSON bridge rather than reproducing the desktop +sample code. ## 2. The lifecycle diff --git a/docs/platform_matrix.zh.md b/docs/platform_matrix.zh.md new file mode 100644 index 0000000..fb4f9db --- /dev/null +++ b/docs/platform_matrix.zh.md @@ -0,0 +1,24 @@ +# Erika 平台能力矩阵 + +本文把“能编译”“CI 构建覆盖”“真机验收”和“有可下载预编译包”分开描述。任何一项为真，都不自动代表其它三项为真。 + +| 平台 | 主要解码/渲染 | C ABI presenter | CI/产物 | 真机验收状态 | +|---|---|---|---|---| +| macOS | VideoToolbox + Metal | 是 | CI 与预编译包 | 持续维护；HDR/EDR 依显示器和系统而定 | +| iOS | VideoToolbox + Metal | 是 | CI 与 XCFramework | 持续维护；需使用真机验证 HDR/后台行为 | +| tvOS | VideoToolbox + Metal | 是 | CI 与 XCFramework | 开发者预览；真机与模拟器分别记录 | +| Windows x64/ARM64 | D3D11VA + D3D11 | 是 | CI 与预编译包 | 持续维护；HDR10 受显示器、驱动和系统设置影响 | +| Android | MediaCodec/软解 + wgpu | 是 | CI 与预编译包 | SDR 已验证；API 35 HDR active path 仍需真机验收 | +| HarmonyOS | AVCodec/软解 + wgpu Vulkan | 是 | 预编译包；CI 覆盖需以 workflow 为准 | 已有真机验证，尚未纳入完整 CI 验收 | +| Linux | 规划中的 wgpu 路径 | 不作为发布承诺 | 无正式预编译发布 | 未验收 | + +## surface 与嵌入选择 + +- Apple：优先 native Metal surface；Flutter 完整播放器优先 window overlay，platform view 用于兼容或诊断。 +- Windows：使用 HWND/D3D11 attach，调用方负责窗口生命周期与 display tick。 +- Android：SDR 使用 TextureView；extended-linear 输出使用 SurfaceView/Hybrid Composition，能力协商失败明确回退 SDR。 +- HarmonyOS：ArkTS 外部纹理提供 `OHNativeWindow`，通过 `erika_presenter_attach_wgpu_surface` attach；平台桥接优先使用 JSON presenter helper。 + +## 发布前记录 + +发布说明应写明每个平台的目标 triple、FFmpeg profile、prebuilt tag、C header 版本、CI 结果及真机验收设备。没有真机结论时应标记“待验收”，不要写成“已完全支持”。 diff --git a/docs/releasing.ja.md b/docs/releasing.ja.md index 007c30d..a8a46d0 100644 --- a/docs/releasing.ja.md +++ b/docs/releasing.ja.md @@ -39,6 +39,20 @@ git push origin v0.1.5 macOS arm64 と x64 はどちらも `macos-26` で cross build し、その後 universal package を合成します。iOS と tvOS の XCFramework も `macos-26` を使用します。Windows x64 は `windows-latest`、ARM64 は `windows-11-arm` で native build します。 +## Release 前の検証 + +`v*` tag を push する前に、clean worktree で次を実行して結果を記録してください。 + +```sh +cargo fmt --all -- --check +cargo test -p erika -p erika_capi +cargo test --workspace +cargo clippy -p erika -p erika_capi --all-targets -- -D warnings +``` + +さらに、影響を受ける example を compile し、公開 `erika.h` と C ABI reference / Flutter +FFI glue の整合性、各 archive の manifest と license、NipaPlay で固定した prebuilt tag を確認してから Release Notes を公開してください。 + ## Flutter で prebuilt を使用 ```sh diff --git a/docs/releasing.md b/docs/releasing.md index 608fbbd..acbcbec 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -72,6 +72,21 @@ To dry-run the builds without publishing, trigger the workflow manually ("Run workflow" / `workflow_dispatch`) — the build jobs run, but the publish job is skipped because it is gated on a tag ref. +## Pre-release validation + +Before pushing a `v*` tag, use a clean worktree and record: + +```sh +cargo fmt --all -- --check +cargo test -p erika -p erika_capi +cargo test --workspace +cargo clippy -p erika -p erika_capi --all-targets -- -D warnings +``` + +Also compile affected examples, compare the public `erika.h` header with the C +ABI reference and Flutter FFI glue, inspect every archive manifest/license, and +verify the pinned prebuilt tag in NipaPlay before publishing release notes. + ## Packaging [`packaging/bundle.sh`](../packaging/bundle.sh) stages and zips a bundle from a diff --git a/docs/releasing.zh.md b/docs/releasing.zh.md index 562e766..38fd759 100644 --- a/docs/releasing.zh.md +++ b/docs/releasing.zh.md @@ -38,6 +38,25 @@ git push origin v0.1.5 macOS arm64 和 x64 都在 `macos-26` 交叉构建，然后合并 universal 包；iOS 和 tvOS XCFramework 同样使用 `macos-26`。Windows x64 在 `windows-latest` 构建，ARM64 在 `windows-11-arm` 原生构建。 +## 发布前检查 + +在推送 `v*` tag 前，维护者应在干净工作树中完成并记录： + +```sh +cargo fmt --all -- --check +cargo test -p erika -p erika_capi +cargo test --workspace +cargo clippy -p erika -p erika_capi --all-targets -- -D warnings +``` + +此外还应： + +- 编译受影响的平台示例，避免示例继续引用已删除的 C ABI、uniform 或配置字段； +- 对比 `crates/erika_capi/include/erika.h`，同步 C ABI 参考文档和 Flutter FFI glue； +- 检查每个预编译归档的 `MANIFEST.txt`、LICENSE、第三方声明及目标架构； +- 更新 package README、CHANGELOG 和 [平台能力矩阵](platform_matrix.zh.md)； +- 在 NipaPlay 中验证固定的 `ERIKA_PREBUILT_TAG`，并同步 NipaPlay 的 pin 与 Release Notes。 + ## Flutter 使用预构建包 ```sh diff --git a/readme/README.en.md b/readme/README.en.md index 49709cd..660b36d 100644 --- a/readme/README.en.md +++ b/readme/README.en.md @@ -25,7 +25,7 @@ The host application provides a rendering surface and sends playback commands - **Subtitles** -- SRT / WebVTT / ASS parsing, libass rendering (statically linked), embedded and external subtitle tracks - **Danmaku** -- Bilibili XML / JSON parsing, DFM+ collision-aware lane layout engine, glyph atlas native GPU rendering - **Playback engine** -- play / pause / stop / seek / rate control, audio-master clock discipline, vsync-quantized frame scheduling -- **C ABI** -- 79 exported functions, opaque handle design, callable from C / C++ / Swift / Dart FFI / any FFI-capable language +- **C ABI** -- opaque handle design with a versioned public header; callable from C / C++ / Swift / Dart FFI / any FFI-capable language. See `erika.h` for the authoritative export set. - **Flutter plugin** -- macOS + iOS + tvOS + Windows + Android + HarmonyOS native view/Texture embedding with platform-native high-dynamic-range surface paths - **wgpu backend** -- Android playback, overlays, capture, and bounded Vulkan/GLES recovery are available; HarmonyOS runs on Vulkan, presenting through OHNativeWindow with OHNativeBuffer zero-copy import; Linux remains planned @@ -79,7 +79,7 @@ Erika provides two C ABI entrypoint families for different embedding scenarios: | `ErikaHandle` | Host manages its own render loop | Host pulls frame data | | `ErikaPresenterHandle` | Erika owns the full playback stack | Host provides a surface and drives `render_tick` | -Header: [`crates/erika_capi/include/erika.h`](crates/erika_capi/include/erika.h) +Header: [`crates/erika_capi/include/erika.h`](../crates/erika_capi/include/erika.h) ## Platform Support diff --git a/readme/README.ja.md b/readme/README.ja.md index a8e647b..45da4cd 100644 --- a/readme/README.ja.md +++ b/readme/README.ja.md @@ -25,7 +25,7 @@ - **字幕** -- SRT / WebVTT / ASS パーサー、libass レンダリング（静的リンク）、埋め込みおよび外部字幕トラック - **弾幕** -- Bilibili XML / JSON パーサー、DFM+ 衝突回避レーン配置エンジン、グリフアトラスによるネイティブ GPU レンダリング - **再生エンジン** -- play / pause / stop / seek / 再生速度制御、音声マスタークロック同期、vsync 量子化フレームスケジューリング -- **C ABI** -- 79 のエクスポート関数、不透明ハンドル設計、C / C++ / Swift / Dart FFI / 任意の FFI 対応言語から呼び出し可能 +- **C ABI** -- 不透明ハンドル設計で、C / C++ / Swift / Dart FFI / 任意の FFI 対応言語から呼び出し可能。正確なエクスポート集合は `erika.h` を参照 - **Flutter プラグイン** -- macOS + iOS + tvOS + Windows + Android + HarmonyOS の native view / Texture embedding と platform-native high-dynamic-range surface path - **wgpu バックエンド** -- Android の playback、overlay、capture、bounded Vulkan/GLES recovery は利用可能。HarmonyOS は Vulkan で動作し、OHNativeWindow で present して OHNativeBuffer を zero-copy import します。Linux は引き続き計画中