Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
71 lines (52 loc) · 2.3 KB

CONTRIBUTING.md

File metadata and controls

71 lines (52 loc) · 2.3 KB
Raw

Contributing

Thanks for helping build OpenStream.

Development Principles

  • Keep OBS output stable: avoid layout shifts in the stage canvas.
  • Keep model integrations behind interfaces so contributors can swap runtimes.
  • Prefer deterministic unit tests for caption, overlay, shader registry, and bbox layout logic.
  • Avoid committing generated model weights, private videos, or personal assets.

Local Workflow

Most Windows contributors should use the repo launcher from the project root:

Copy-Item .env.example .env.local
notepad .env.local
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1

Use -SkipInstall after the first successful run if you want a quieter startup.

Run the full local test suite before opening a PR:

powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1

Manual frontend workflow:

cd frontend
bun install
bun run test
bun run dev

Manual backend workflow:

cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest
uvicorn openstream_api.main:app --reload --port 8710

Pull Request Checklist

  • Keep .env.local, API keys, model weights, recordings, and local videos out of git.
  • Include or update focused tests for caption parsing, overlay rules, shader registry behavior, bbox layout, or backend WebSocket flow when those areas change.
  • Confirm the OBS stage still renders at a stable 1920x1080 coordinate system.
  • Update README.md or docs/ when adding a new user-visible control, model backend, shader, or launcher option.
  • Keep model integrations behind SpeechTranscriber or VisionGrounder style interfaces.

Project Areas

  • Shaders live in the frontend shader registry and should include defaults, labels, and UI-safe uniforms.
  • Caption and word-overlay logic should stay deterministic and unit-testable.
  • Gemini Live, Moonshine, and LFM code should expose useful debug state without leaking secrets.
  • Shared presets belong in presets/ and should be safe to paste into issues.

Good First Issues

  • Add a new shader to the shader registry.
  • Add caption presets for common livestream formats.
  • Improve the Moonshine streaming adapter.
  • Add an LFM2.5-VL runtime implementation using ONNX, MLX, or another local backend.
  • Add golden-frame tests for new shaders.