Skip to content

README.md

Latest commit

 

History

History
197 lines (151 loc) · 8.33 KB

README.md

File metadata and controls

197 lines (151 loc) · 8.33 KB
Raw

StreamBridge

Turn your phone's camera and mic streams (e.g. EZ-Cam-Mic) into a real webcam and microphone on Windows, Linux, and macOS.

License: MIT Platforms Python

Overview · Requirements · Download · Source Setup · Usage · Development · Architecture

Quick Overview

StreamBridge connects to video and audio streams broadcast by your mobile phone (such as EZ-Cam-Mic, IP Webcam, or RTSP apps) and outputs them directly to standard virtual devices. Apps like Zoom, Microsoft Teams, Discord, OBS Studio, or browser meetings recognize StreamBridge immediately as physical hardware.

Video URL:  http://192.168.1.5:8080/video        (or just 192.168.1.5:8080/video)
Audio URL:  https://10.0.2.16:4747/audio.wav      ("Same phone" auto-fills from video)
Login:      optional (e.g. user / pass or https://user:[email protected]:4747/video)

Platform Requirements

StreamBridge uses standard virtual video/audio loopback devices. It never installs drivers behind your back; on first run, the built-in Welcome / Setup check detects installed devices and links directly to official driver installers:

Platform Virtual Camera Virtual Microphone Required Driver / Setup (One-Time)
Windows OBS Virtual Camera CABLE Output OBS Studio 26+ · VB-CABLE
Linux StreamBridge Camera StreamBridge Microphone v4l2loopback (package) · PipeWire / PulseAudio
macOS OBS Virtual Camera BlackHole 2ch OBS Studio 26+ · BlackHole 2ch

Tip

Use only what you need: Camera-only streaming requires only the camera driver; microphone-only streaming requires only the audio driver.

Download

Pre-built standalone releases (no Python installation required) are published on the Releases page:

OS / Architecture Package How to Launch
Windows (x64) StreamBridge-vX.Y.Z-windows-x64.zip Unzip and launch StreamBridge.exe
macOS (arm64) StreamBridge-vX.Y.Z-macos-arm64.zip Move to Applications and open StreamBridge.app
Linux (x64) StreamBridge-vX.Y.Z-linux-x64.tar.gz Extract and run ./start-streambridge.sh

Verifying Release Integrity

Release assets include free cryptographic build provenance attestations from GitHub Actions:

# Verify GitHub build provenance attestation
gh attestation verify StreamBridge-vX.Y.Z-windows-x64.zip --repo roaxio/StreamBridge

Note

Unsigned Release Notice:

  • Windows SmartScreen: Click More info → Run anyway.
  • macOS Gatekeeper: Right-click StreamBridge.app → Open → Open, or run: 
    xattr -dr com.apple.quarantine StreamBridge.app

Running from Source

Windows

  1. Camera: Install OBS Studio. Launch OBS once, click Start Virtual Camera, then Stop. (OBS does not need to stay open after this and can be closed; StreamBridge connects directly to the registered virtual camera driver).
  2. Microphone: Install VB-CABLE as Administrator and reboot.
  3. In meeting apps (Zoom, Discord, Teams), select:
    • Camera: OBS Virtual Camera
    • Microphone: CABLE Output

Run using the developer helper script:

scripts\windows\dev\run.bat

Or set up manually in a Python virtual environment:

py -m venv .venv
.venv\Scripts\activate
pip install -e .
streambridge

Linux

  1. Install prerequisites: 
    sudo apt install v4l2loopback-dkms pulseaudio-utils python3-venv python3-tk
sudo modprobe v4l2loopback devices=1 exclusive_caps=1 card_label="StreamBridge Camera"
  2. Launch StreamBridge: 
    scripts/linux/dev/run.sh
# or manually:
python3 -m venv .venv && source .venv/bin/activate && pip install -e . && streambridge
  3. In your apps, select StreamBridge Camera and StreamBridge Microphone.

macOS

  1. Install OBS Studio and BlackHole 2ch.
  2. Run StreamBridge: 
    python3 -m venv .venv && source .venv/bin/activate && pip install -e . && streambridge
  3. In your apps, select OBS Virtual Camera and BlackHole 2ch.

Features & Usage

Key Capabilities

Capability Highlights Options & Controls
🧪 Pre-Flight Testing Probes stream URLs and checks resolution, codecs, and audio sample rates before launching virtual hardware. One-click Test button or CLI --test
🔀 Independent Channels Stream camera-only, microphone-only, or both simultaneously. Video URL, Audio URL, or both
🔄 Auto-Reconnect & Shielding Recovers from Wi-Fi dropouts with exponential backoff (0.5 s to 10 s). Outputs clean black frames during reconnects so meeting apps never freeze or crash. Automatic retry loop (transparent to apps)
📐 Adaptive Video Sizing Preserves aspect ratio with zero distortion; reopens hardware cleanly on mid-stream orientation shifts. Auto (clamped 160px–4K), 1080p, 720p, 480p, or custom WxH
⚡ Low-Latency Audio Pull-driven jitter buffer prevents delay buildup and smoothly corrects clock drift. • Low (~30 ms buffer, default)
• Normal (~60 ms buffer)
• Stable (~150 ms buffer)
🔒 Privacy & Security Passwords are masked across UI and logs. Enforces TLS on public endpoints while allowing self-signed certs on private LANs. Optional OS keychain via Remember password
🧹 Clean Reset Complete zero-residue cleanup of configs, recent URL history, logs, and stored credentials. Menu Reset to defaults… or CLI --reset [--logs]

Command Line Interface

StreamBridge can be run from the command line using either the pre-built standalone executable or from source inside an activated virtual environment:

  • Standalone Release (no Python required):
    • Windows: StreamBridge.exe [options]
    • Linux: ./StreamBridge [options]
    • macOS: /Applications/StreamBridge.app/Contents/MacOS/StreamBridge [options]
  • From Source (activate .venv first):
    • Windows: Run .venv\Scripts\activate then streambridge [options] (or use scripts\windows\dev\run.bat [options])
    • Linux / macOS: Run source .venv/bin/activate then streambridge [options] (or use scripts/linux/dev/run.sh [options])
# Launch GUI (run with no flags)
streambridge

# Headless streaming with audio and video
streambridge --video http://192.168.1.5:8080/video --audio http://192.168.1.5:8080/audio.wav

# Common CLI Options
streambridge --video URL [--audio URL] [--size Auto|1080p|720p|480p|WxH] [--fps 30]
             [--audio-latency low|normal|stable] [--audio-output NAME]
             [--test] [--check] [--reset [--logs] [--yes]] [--version] [-v]

Development

# Environment setup
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Linting & unit tests
ruff check .
pytest

# OS-specific validation scripts
scripts/windows/dev/check_all.bat   # Windows
scripts/linux/dev/check_all.sh       # Linux
scripts/macos/dev/check_all.sh       # macOS

Standalone Packaging

  • Local Dev Builds: scripts/<os>/dev/build_<os>.*
  • Release-Identical Builds: scripts/<os>/build_onefile_<os>.*

Documentation & Governance