# adriansajjan/webcodecs-samples architecture

> Architecture diagram of the GitHub repository adriansajjan/webcodecs-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adriansajjan/webcodecs-samples
- Repository: https://github.com/adriansajjan/webcodecs-samples

## Overview

##### Project type and purpose
- This is a browser-based, single-page application (SPA) built with Vite and TypeScript.
- It provides four main multimedia features using the WebCodecs and Web APIs:
- Screen recording (in MP4 or WebM)
- Audio extraction from video files
- Video cropping
- Custom video playback with demuxing and rendering

##### File structure
- Top-level:
- index.html, main.ts – bootstraps the SPA
- router.ts + src/routes – maps URL paths to feature modules
- src/features – each feature lives in its own subfolder
· audio-extractor/extract.ts
· screen-recorder/recorder.ts, worker.ts, codec/*, constants/*
· video-cropper/cropper.ts
· video-player/player.ts, demuxer.ts, renderer/*, worker.ts, constants/*
- src/shared – cross-feature utilities and type definitions
- No backend: all processing runs in the browser or dedicated Web Workers.
- Configuration: Vite (vite.config.js), TypeScript (tsconfig.json), package.json for dependencies.

##### README
- Project title “Webcodecs Screen Recorder” confirms focus on WebCodecs-based media manipulation in the browser.

##### Main components and interactions
a. Components
1. User (actor)
2. Browser / SPA shell
3. Router & Route modules (router.ts + src/routes)
4. Feature modules (UI + controller logic)
- ScreenRecorder
- AudioExtractor
- VideoCropper
- VideoPlayer
5. Web Workers
- screen-recorder worker (worker.ts)
- video-player worker (worker.ts)
6. Codec implementations (MP4, WebM)
7. Shared utilities (utils.ts) & types
8. External Web APIs
- MediaDevices.getDisplayMedia
- WebCodecs API (VideoEncoder, AudioEncoder, VideoDecoder, AudioDecoder)
- Canvas2D or WebGL for rendering
- Web Audio API
9. Local file storage / Download API

b. Relationships & Data Flows
1. User → SPA → Router → Feature UI
2. ScreenRecorder UI → Recorder.ts
- Recorder.ts invokes getDisplayMedia, pipes MediaStream → Worker via postMessage
- Worker loads appropriate codec (MP4 or WebM) → uses WebCodecs encoders → outputs byte chunks back to main thread → triggers download
3. AudioExtractor UI → extract.ts
- Reads input file → uses WebCodecs decoders → extracts audio track → re-encodes (if needed) → provides audio file
4. VideoCropper UI → cropper.ts
- Loads source video → uses HTMLVideoElement + Canvas2D to crop frames → reassembles via WebCodecs encoders → download
5. VideoPlayer UI → player.ts
- Loads video file → demuxer.ts splits streams → Worker decodes frames via WebCodecs decoders → sends frames to renderer (2D or WebGL) and audio packets to Web Audio API

c. Architectural patterns & principles
- Feature-based modularization: each capability lives in its own folder with its own entrypoint and worker.
- Separation of concerns:
- UI logic in controllers (player.ts, recorder.ts, etc.)
- Heavy CPU work in Web Workers
- Codec logic abstracted behind base.ts and specific implementations
- Shared types/utilities in src/shared
- Event-driven data flow: uses constants/events.ts to decouple modules.

d. Key technologies
- TypeScript & Vite (module bundling)
- WebCodecs API (Video/AudioEncoder, Decoder)
- Web Workers for off-main-thread processing
- Canvas2D or WebGL for rendering video frames
- Web Audio API for playback
- MediaDevices API for screen capture

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actor
    User(("User")):::actor

    %% External APIs
    subgraph "External Web APIs" 
        direction TB
        MD["MediaDevices.getDisplayMedia"]:::external
        WC["WebCodecs API"]:::external
        CV["Canvas2D / WebGL"]:::external
        WA["Web Audio API"]:::external
        DL["Download API / FileSaver"]:::external
    end

    %% Browser Container
    subgraph "Browser / SPA Shell" 
        direction TB
        %% Bootstrapping
        Main["index.html / main.ts"]:::boot
        click Main "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/main.ts"
        click Main "https://github.com/adriansajjan/webcodecs-samples/blob/main/index.html"

        %% Router & Routes
        Router["Router & Routes"]:::router
        click Router "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/router.ts"
        HomeRoute["Home Route"]:::router
        click HomeRoute "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/routes/home.ts"
        RecorderRoute["Recorder Route"]:::router
        click RecorderRoute "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/routes/recorder.ts"
        PlayerRoute["Player Route"]:::router
        click PlayerRoute "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/routes/player.ts"
        CropRoute["Crop Route"]:::router
        click CropRoute "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/routes/crop.ts"

        %% Features Container
        subgraph "Features"
            direction TB

            %% ScreenRecorder Feature
            subgraph "ScreenRecorder" 
                direction TB
                SR_UI["Recorder.ts (Controller)"]:::controller
                click SR_UI "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/recorder.ts"
                SR_Worker["Worker"]:::worker
                click SR_Worker "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/worker.ts"
                subgraph "Codecs" 
                    direction TB
                    SR_Base["base.ts"]:::codec
                    click SR_Base "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/codec/base.ts"
                    SR_MP4["mp4.ts"]:::codec
                    click SR_MP4 "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/codec/mp4.ts"
                    SR_WebM["webm.ts"]:::codec
                    click SR_WebM "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/codec/webm.ts"
                end
                SR_Events["events.ts"]:::shared
                click SR_Events "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/screen-recorder/constants/events.ts"
            end

            %% AudioExtractor Feature
            subgraph "AudioExtractor"
                direction TB
                AE_UI["extract.ts (Controller)"]:::controller
                click AE_UI "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/audio-extractor/extract.ts"
            end

            %% VideoCropper Feature
            subgraph "VideoCropper"
                direction TB
                VC_UI["cropper.ts (Controller)"]:::controller
                click VC_UI "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-cropper/cropper.ts"
            end

            %% VideoPlayer Feature
            subgraph "VideoPlayer"
                direction TB
                VP_UI["player.ts (Controller)"]:::controller
                click VP_UI "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/player.ts"
                Demuxer["demuxer.ts"]:::shared
                click Demuxer "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/demuxer.ts"
                VP_Worker["Worker"]:::worker
                click VP_Worker "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/worker.ts"
                subgraph "Renderer"
                    direction TB
                    R2D["2d.ts"]:::codec
                    click R2D "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/renderer/2d.ts"
                end
                VP_Events["constants/events.ts"]:::shared
                click VP_Events "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/constants/events.ts"
                VP_IF1["interfaces/events.ts"]:::shared
                click VP_IF1 "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/interfaces/events.ts"
                VP_IF2["interfaces/player.ts"]:::shared
                click VP_IF2 "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/interfaces/player.ts"
                VP_IF3["interfaces/renderer.ts"]:::shared
                click VP_IF3 "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/features/video-player/interfaces/renderer.ts"
            end

            %% Shared Utilities
            subgraph "Shared Utilities & Types"
                direction TB
                Utils["utils.ts"]:::shared
                click Utils "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/shared/libs/utils.ts"
                SharedEvents["shared types/events.ts"]:::shared
                click SharedEvents "https://github.com/adriansajjan/webcodecs-samples/blob/main/src/shared/types/events.ts"
            end

        end
    end

    %% Configuration
    Config["vite.config.js / tsconfig.json / package.json"]:::config
    click Config "https://github.com/adriansajjan/webcodecs-samples/blob/main/vite.config.js"
    click Config "https://github.com/adriansajjan/webcodecs-samples/blob/main/tsconfig.json"
    click Config "https://github.com/adriansajjan/webcodecs-samples/blob/main/package.json"

    %% Sample Asset
    Sample["public/videos/sample.mp4"]:::asset
    click Sample "https://github.com/adriansajjan/webcodecs-samples/blob/main/public/videos/sample.mp4"

    %% Connections
    User -->|"interacts with"| Main
    Main --> Router
    Router --> HomeRoute
    Router --> RecorderRoute
    Router --> PlayerRoute
    Router --> CropRoute

    RecorderRoute --> SR_UI
    SR_UI -->|"postMessage(mediaStream)"| SR_Worker
    SR_Worker --> SR_Base
    SR_Worker --> SR_MP4
    SR_Worker --> SR_WebM
    SR_UI --> MD
    SR_Worker -->|"encoded chunks"| DL

    AE_UI -->|"reads file"| WC
    AE_UI -->|"decode/encode"| WC
    AE_UI -->|"provides audio"| DL

    VC_UI -->|"load video"| Sample
    VC_UI --> CV
    VC_UI -->|"crop frames"| CV
    VC_UI --> WC
    VC_UI -->|"output"| DL

    PlayerRoute --> VP_UI
    VP_UI --> Sample
    VP_UI --> Demuxer
    Demuxer --> VP_Worker
    VP_Worker --> WC
    VP_Worker --> R2D
    R2D --> CV
    VP_Worker --> WA
    VP_UI --> WA

    %% Shared
    SR_UI --- Utils
    AE_UI --- Utils
    VC_UI --- Utils
    VP_UI --- Utils

    %% External API usage
    SR_UI --> MD
    SR_Worker --> WC
    VP_Worker --> WC
    VP_Worker --> WA
    VC_UI --> CV

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px;
    classDef external stroke-dasharray: 5 5,fill:#fff,stroke:#555;
    classDef boot fill:#bbf,stroke:#333,stroke-width:1px;
    classDef router fill:#bbf,stroke:#333,stroke-width:1px;
    classDef controller fill:#afa,stroke:#333,stroke-width:1px;
    classDef worker fill:#dca,stroke:#333,stroke-width:1px;
    classDef codec fill:#fc9,stroke:#333,stroke-width:1px;
    classDef shared fill:#ccc,stroke:#333,stroke-width:1px;
    classDef config fill:#eee,stroke:#333,stroke-width:1px;
    classDef asset fill:#eef,stroke:#333,stroke-width:1px;
```
