From 4131359c8bf49a128a78dfda873df41ce7d224d1 Mon Sep 17 00:00:00 2001 From: Wojciech Kozyra Date: Thu, 19 Dec 2024 14:44:17 +0100 Subject: [PATCH] Add internal docs how to use this repo --- DEVELOPMENT.md | 188 +++++++++++++++++++++++++++++++++++++++++++++++++ ts/README.md | 13 ---- 2 files changed, 188 insertions(+), 13 deletions(-) create mode 100644 DEVELOPMENT.md delete mode 100644 ts/README.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..54b83fadb --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,188 @@ +# Development process + +## Rust + +### Binaries + +Directory **`src/bin`** in Rust crate have a special meaning. Each **`*.rs`** file or directory +(with **`main.rs`**) is a binary that can be executed with: + +``` +cargo run --bin +``` + +For example: + +``` +cargo run --bin package_for_relase +``` +to run **`./src/bin/package_for_release/main.rs`**. + +or + +``` +cargo run --bin main_process +``` + +to run **`./src/bin/main_process.rs`** + + +To run binary from specific create you need to run the command from that crate directory. + +#### `live_compositor` create (root) + +- `package_for_relase` - builds release binaries that can be uploaded to GitHub Releases +- `main_process` - main binary to start standalone compositor +- `process_helper` - starts secondary processes that communicate with `main_process` + to enable web rendering with Chromium + +#### `integration_tests` crate + +- `play_rtp_dump` - helper to play RTP dumps generated in tests from **`./integration_tests/src/tests`**. + Useful to verify if new tests generated correctly or to see what is wrong when test is failing. +- `generate_rtp_from_file` - helper to generate new input files that can be used for new tests in + **`./integration_tests/src/tests`**. + +#### `generate` create + +This is crate when we keep most of our utils that generate something in repo: + +- `generate_docs_examples` - generates WEBP files with examples for documentation. +- `generate_docs_example_inputs` - helper for `generate_docs_examples` (generates inputs for that binary). +- `generate_from_types` - generate JSON schema from `compositor_api` types. It needs to be called every + time API is changed and regenerated file needs to be committed. (It also generates Markdown docs, but + this will be soon removed) +- `generate_playground_inputs` - TODO + +### Examples + +TODO + +### Tests + +We have 3 main types of test: +- Small amount of regular unit tests spread over codebase. +- Snapshot tests that render specific image and save them as PNG. + - Generated images are located in **`./snapshot_tests/snapshots/render_snapshots`** directory. + - JSON files representing tested scenes are in **`./snapshot_tests`** directory + - Actual Rust tests are in **`./src/snapshot_tests`**. + - For example: + - Test is located in **`./src/snapshot_tests/view_tests.rs`** + - Test is rendering scene described by **`./snapshot_tests/view/border_radius.scene.json`** + - Test is rendering output (or comparing with the old version) to + **`./snapshot_tests/snapshots/render_snapshots/view/border_radius_0_output_1.png`** +- End-to-end tests that are basically snapshot tests, but compare entire videos. + - Generated stream dumps are located in **`./snapshot_tests/snapshots/rtp_packet_dumps`** directory. + - Tests are implemented in **`./integration_tests/src/tests`** directory. + - Some of the test here might be fragile if running along a lot of CPU intensive + tasks. That is why **`./.config/nextest.toml`** is limiting concurrency of some tests on CI. + +Initially when setting up the repo, or when checking out different branch you need to update +submodule to the correct version by running +``` +git submodule update --init --checkout +``` + +> Carefully read output of the command to make sure it worked. It will fail if you have uncommitted +changes in the **`./snapshot_tests/snapshots`** directory. + +To run all test run: + +``` +cargo nextest run --workspace --profile ci +``` + +If you don't have `nextest` installed you can add it with; + +``` +cargo install cargo-nextest +``` + +To run specific test add name of the function or crate at the end: + +e.g. + +``` +cargo nextest run --workspace audio_mixing_with_offset +``` + +will run a test from **`./integration_tests/src/tests/audio_only.rs`** + +#### Updating snapshots + +By default, snapshot tests generate new output and compare with the old version committed +to repo. If version in repo is different or missing then tests will fail. + +To generate snapshots for new tests, or update those that should change you need to enable +`update_snapshots` feature when running tests. It is recommended to only run that command +for specific tests, especially **`./integration_tests/src/tests`** + +e.g. + +``` +cargo nextest run --workspace --features update_snapshots audio_mixing_with_offset +``` + +will run a test from **./integration_tests/src/tests/audio_only.rs** and if output changed the update the snapshot. + +If you made changes that modify the snapshot: +- Create PR in https://github.com/membraneframework-labs/video_compositor_snapshot_tests repo. +- Create PR in live compositor repo with link to the snapshot repo PR. +- Merge them together. + +## TypeScript SDK + +### Packages + +- `live-compositor` - React components and common API types. (analog of `react` package). +- `@live-compositor/core` - Base implementation that is used by packages like `@live-compositor/node`. +- `@live-compositor/node` - Node.js SDK for compositor (analog of `react-dom` for Node.js) +- `@live-compositor/web-wasm` - Browser SDK for compositor that includes compositor compiled to WASM (analog of `react-dom` for Node.js) +- `@live-compositor/browser-render` - Rendering ending from LiveCompositor compiled to WASM. + - Run `pnpm run build-wasm` to build WASM bundle from Rust code + - Run `pnpm run build` to build JS code (WASM has to be build earlier, or use `build:all` in root directory to build everything) + +### API compatibility + +> WARNING this is the goal, it is currently not true. + +SDK should be always compatible with version of code from the repo. If you are changing API the changes to SDK should land in the same PR. + +### Examples + +To bootstrap repo run: + +``` +pnpm install && pnpm build:all +``` + +After that you can run only `pnpm run build` to rebuild if Rust code did not change. + +#### Node.js: **`./ts/examples/node-examples/`** + +To run example **`./ts/examples/node-examples/src/simple.tsx`**, go to **`./ts/examples/node-examples`** and run: + +``` +pnpm run ts-node ./src/simple.tsx +``` + +> TODO: instructions below needs to be automated to build Rust automatically and point examples to this binary + +To run Node.js example against Rust code from the repo you need to in the root directory run: + +``` +cargo build -r --no-default-features +export LIVE_COMPOSITOR_PATH=$(pwd)/target/release/main_process +``` + +#### Web WASM: **`./ts/examples/vite-browser-render`** + +Run + +``` +pnpm run dev +``` + +Open `localhost:5173` in the browser + +If Rust code changes you need to rebuild WASM with `pnpm run build-wasm`. diff --git a/ts/README.md b/ts/README.md deleted file mode 100644 index 1d21b144b..000000000 --- a/ts/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# TypeScript SDK - -## Packages - -- `live-compositor` - Provide core React components that can be used to define a composition of a video stream. -- `@live-compositor/node` - Provides API to create and manage LiveCompositor instances for Node.js environment. -- `@live-compositor/core` - Shared runtime-independent implementation that is used by packages like `@live-compositor/node`. -- `@live-compositor/browser-render` - Rendering implementation from LiveCompositor compiled to WASM and uses WebGL as rendering backend. - -## Examples - -- `./examples/node-examples` - Few examples of using LiveCompositor with TypeScript from Node.js -- `./examples/vite-browser-render` - Example of using `@live-compositor/browser-render` package in a Vite project.