# saprecar/otter architecture

> Architecture diagram of the GitHub repository saprecar/otter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saprecar/otter
- Repository: https://github.com/saprecar/otter

## Overview

Otter turns an Android camera or mobile-browser camera into a PC webcam, with desktop controls for connection, camera settings, backgrounds, and virtual-camera output. The principal workflow is mobile capture and streaming, desktop reception and frame processing, then delivery to an OS virtual camera or browser stream. The repository also contains a browser-based controller/streamer and duplicated stable desktop and Android editions. Edges reflect shown imports and calls or README-described behavior; unsampled web and Android internals are represented cautiously.

Main entry points: [`Dev/desktop/cambridge_receiver.py`](https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_receiver.py) (Stream Receiver), [`Dev/desktop/otter_web_server.py`](https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_web_server.py) (Web Controller), [`Dev/desktop/otter_app.py`](https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_app.py) (Desktop Controller), [`Dev/android/app/src/main/java/org/understory/cambridge/OtterStreamService.java`](https://github.com/saprecar/otter/blob/main/Dev/android/app/src/main/java/org/understory/cambridge/OtterStreamService.java) (Android Stream Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile Capture"]
  node_android_app["Android Camera App<br/>[MainActivity.java]"]
  node_android_stream["Android Stream Service"]
  node_mobile_browser["Mobile Web Streamer"]
  node_stable_android["Stable Android Editions<br/>[MainActivity.java]"]
end

subgraph group_desktop["Desktop Control"]
  node_desktop_ui["Desktop Controller<br/>[otter_app.py]"]
  node_web_ui["Web Controller"]
  node_discovery["Network Discovery"]
  node_adb_manage["ADB Management<br/>[manage_adb.py]"]
  node_stable_desktop["Stable Desktop Edition"]
end

subgraph group_transport["Connection and Receive"]
  node_adb_tunnel["ADB Tunnel<br/>[adb_tunnel.py]"]
  node_receiver["Stream Receiver"]
  node_control_client["Camera Control Client"]
  node_virtual_bg["Background Processing"]
end

subgraph group_output["Video Outputs"]
  node_linux_output["Linux V4L2 Bridge"]
  node_obs_output["OBS Camera Bridge"]
  node_unity_output["Unity Camera Bridge"]
end

node_user(("User"))
node_conference_apps(("Video Applications"))

node_user -->|"configures camera"| node_android_app
node_android_app -.->|"starts streaming"| node_android_stream
node_android_stream -->|"streams video"| node_receiver
node_user -->|"opens streamer"| node_mobile_browser
node_mobile_browser -->|"sends camera frames"| node_web_ui
node_user -->|"controls session"| node_desktop_ui
node_desktop_ui -.->|"starts receiver"| node_receiver
node_desktop_ui -->|"launches controller"| node_web_ui
node_desktop_ui -->|"detects network"| node_discovery
node_desktop_ui -->|"manages ADB"| node_adb_manage
node_web_ui -->|"starts receiver"| node_receiver
node_web_ui -->|"sets USB forwarding"| node_adb_tunnel
node_web_ui -->|"detects adapters"| node_discovery
node_adb_tunnel -->|"locates portable ADB"| node_adb_manage
node_receiver -->|"queries device"| node_control_client
node_receiver -->|"processes frames"| node_virtual_bg
node_receiver -->|"writes frames"| node_linux_output
node_receiver -->|"writes frames"| node_obs_output
node_receiver -->|"writes frames"| node_unity_output
node_linux_output -->|"exposes webcam"| node_conference_apps
node_obs_output -->|"exposes webcam"| node_conference_apps
node_unity_output -->|"exposes webcam"| node_conference_apps
node_web_ui -->|"serves MJPEG"| node_conference_apps
node_stable_desktop -.->|"duplicates runtime"| node_receiver
node_stable_android -.->|"duplicates mobile app"| node_android_stream

click node_android_app "https://github.com/saprecar/otter/blob/main/Dev/android/app/src/main/java/org/understory/cambridge/MainActivity.java"
click node_android_stream "https://github.com/saprecar/otter/blob/main/Dev/android/app/src/main/java/org/understory/cambridge/OtterStreamService.java"
click node_mobile_browser "https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_web_server.py"
click node_desktop_ui "https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_app.py"
click node_web_ui "https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_web_server.py"
click node_discovery "https://github.com/saprecar/otter/blob/main/Dev/desktop/network_discovery.py"
click node_adb_manage "https://github.com/saprecar/otter/blob/main/Dev/desktop/manage_adb.py"
click node_adb_tunnel "https://github.com/saprecar/otter/blob/main/Dev/desktop/adb_tunnel.py"
click node_receiver "https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_receiver.py"
click node_control_client "https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_control.py"
click node_virtual_bg "https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_receiver.py"
click node_linux_output "https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/linux_v4l2_bridge.py"
click node_obs_output "https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/obs_virtualcam_bridge.py"
click node_unity_output "https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/unity_capture_bridge.py"
click node_stable_desktop "https://github.com/saprecar/otter/tree/main/Stable/Stable_Desktop_Client"
click node_stable_android "https://github.com/saprecar/otter/blob/main/Stable/stable_playstore_version/app/src/main/java/org/understory/cambridge/MainActivity.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android_app,node_android_stream,node_mobile_browser,node_stable_android,node_user toneBlue
class node_desktop_ui,node_web_ui,node_discovery,node_adb_manage,node_stable_desktop toneAmber
class node_adb_tunnel,node_receiver,node_control_client,node_virtual_bg toneMint
class node_linux_output,node_obs_output,node_unity_output toneRose
class node_conference_apps toneIndigo
```

## Components

### Mobile Capture

- [Android Camera App](https://github.com/saprecar/otter/blob/main/Dev/android/app/src/main/java/org/understory/cambridge/MainActivity.java): `Dev/android/app/src/main/java/org/understory/cambridge/MainActivity.java`
- [Android Stream Service](https://github.com/saprecar/otter/blob/main/Dev/android/app/src/main/java/org/understory/cambridge/OtterStreamService.java): `Dev/android/app/src/main/java/org/understory/cambridge/OtterStreamService.java`
- [Mobile Web Streamer](https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_web_server.py): `Dev/desktop/otter_web_server.py`
- [Stable Android Editions](https://github.com/saprecar/otter/blob/main/Stable/stable_playstore_version/app/src/main/java/org/understory/cambridge/MainActivity.java): `Stable/stable_playstore_version/app/src/main/java/org/understory/cambridge/MainActivity.java`

### Desktop Control

- [Desktop Controller](https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_app.py): `Dev/desktop/otter_app.py`
- [Web Controller](https://github.com/saprecar/otter/blob/main/Dev/desktop/otter_web_server.py): `Dev/desktop/otter_web_server.py`
- [Network Discovery](https://github.com/saprecar/otter/blob/main/Dev/desktop/network_discovery.py): `Dev/desktop/network_discovery.py`
- [ADB Management](https://github.com/saprecar/otter/blob/main/Dev/desktop/manage_adb.py): `Dev/desktop/manage_adb.py`
- [Stable Desktop Edition](https://github.com/saprecar/otter/tree/main/Stable/Stable_Desktop_Client): `Stable/Stable_Desktop_Client`

### Connection and Receive

- [ADB Tunnel](https://github.com/saprecar/otter/blob/main/Dev/desktop/adb_tunnel.py): `Dev/desktop/adb_tunnel.py`
- [Stream Receiver](https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_receiver.py): `Dev/desktop/cambridge_receiver.py`
- [Camera Control Client](https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_control.py): `Dev/desktop/cambridge_control.py`
- [Background Processing](https://github.com/saprecar/otter/blob/main/Dev/desktop/cambridge_receiver.py): `Dev/desktop/cambridge_receiver.py`

### Video Outputs

- [Linux V4L2 Bridge](https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/linux_v4l2_bridge.py): `Dev/desktop/driver/linux_v4l2_bridge.py`
- [OBS Camera Bridge](https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/obs_virtualcam_bridge.py): `Dev/desktop/driver/obs_virtualcam_bridge.py`
- [Unity Camera Bridge](https://github.com/saprecar/otter/blob/main/Dev/desktop/driver/unity_capture_bridge.py): `Dev/desktop/driver/unity_capture_bridge.py`

### Other components

- **User**
- **Video Applications**

## Connections

- User → Android Camera App: configures camera (evidence: `README.md`)
- Android Camera App → Android Stream Service: starts streaming
- Android Stream Service → Stream Receiver: streams video (evidence: `README.md`)
- User → Mobile Web Streamer: opens streamer (evidence: `README.md`)
- Mobile Web Streamer → Web Controller: sends camera frames (evidence: `README.md`)
- User → Desktop Controller: controls session (evidence: `README.md`)
- Desktop Controller → Stream Receiver: starts receiver (evidence: `Dev/desktop/otter_app.py`)
- Desktop Controller → Web Controller: launches controller (evidence: `Dev/desktop/otter_app.py`)
- Desktop Controller → Network Discovery: detects network (evidence: `Dev/desktop/otter_app.py`)
- Desktop Controller → ADB Management: manages ADB (evidence: `Dev/desktop/otter_app.py`)
- Web Controller → Stream Receiver: starts receiver (evidence: `Dev/desktop/otter_web_server.py`)
- Web Controller → ADB Tunnel: sets USB forwarding (evidence: `Dev/desktop/otter_web_server.py`)
- Web Controller → Network Discovery: detects adapters (evidence: `Dev/desktop/otter_web_server.py`)
- ADB Tunnel → ADB Management: locates portable ADB (evidence: `Dev/desktop/adb_tunnel.py`)
- Stream Receiver → Camera Control Client: queries device (evidence: `Dev/desktop/cambridge_receiver.py`)
- Stream Receiver → Background Processing: processes frames (evidence: `Dev/desktop/cambridge_receiver.py`)
- Stream Receiver → Linux V4L2 Bridge: writes frames (evidence: `Dev/desktop/cambridge_receiver.py`)
- Stream Receiver → OBS Camera Bridge: writes frames (evidence: `Dev/desktop/cambridge_receiver.py`)
- Stream Receiver → Unity Camera Bridge: writes frames (evidence: `Dev/desktop/cambridge_receiver.py`)
- Linux V4L2 Bridge → Video Applications: exposes webcam (evidence: `README.md`)
- OBS Camera Bridge → Video Applications: exposes webcam (evidence: `README.md`)
- Unity Camera Bridge → Video Applications: exposes webcam (evidence: `README.md`)
- Web Controller → Video Applications: serves MJPEG (evidence: `README.md`)
- Stable Desktop Edition → Stream Receiver: duplicates runtime (evidence: `Stable/Stable_Desktop_Client/otter_app.py`)
- Stable Android Editions → Android Stream Service: duplicates mobile app
