OpenParable
Skip to content
← Back to skills

Provider Analysis

Apps & Automation
provider-analysis

Provider Analysis is an Agent Skill for apps & automation published in the fossasia/voxbento repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use this skill when integrating, debugging, or auditing third-party provider integrations (transcription APIs, MediaMTX, Jitsi, future Eventyay API integration).

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/fossasia/voxbento/blob/HEAD/.agents/skills/provider-analysis/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/provider-analysis, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Skill: Provider Analysis

Use this skill when integrating, debugging, or auditing third-party provider integrations (transcription APIs, MediaMTX, Jitsi, future Eventyay API integration).


MediaMTX

Role: Media server — WHIP ingest, WHEP playback, RTSP for transcription.

Key integration points

EndpointUsed byPurpose
{MEDIAMTX_WHIP_BASE}/{path}/whipBrowser (JS)Interpreter audio ingest
{MEDIAMTX_WHIP_BASE}/{path}/whepBrowser (JS)Listener audio playback
rtsp://mediamtx:8554/{path}ffmpeg (Python)Transcription audio source
{MEDIAMTX_API_BASE}/v3/config/paths/add/{path}FastAPI (_ensure_mediamtx_path)Create named path with alwaysAvailable
{MEDIAMTX_API_BASE}/v3/config/paths/patch/{path}FastAPI (fallback)Update existing path config
{MEDIAMTX_API_BASE}/v3/paths/listFastAPI (_check_mediamtx)Reachability check

alwaysAvailable path creation

  • Called before returning WHIP URL or rendering booth page.
  • Creates named path so WHEP readers survive publisher handoffs.
  • Cache: _created_paths set prevents duplicate API calls.
  • Idempotent: if path exists, PATCHes it to ensure alwaysAvailable: True.

overridePublisher

Set in mediamtx.yml — allows a new WHIP publisher to kick the previous one. Enables seamless handoff when coordinator reassigns active interpreter.

Reachability check

await _check_mediamtx()  # returns True if API responds < 500

Used by /healthz and booth page template.


Jitsi Meet

Role: Floor session monitoring — receive-only iframe embedded in interpreter booth.

Integration

  • Embedded as an iframe in templates/interpreter_booth.html.
  • URL: room-specific Jitsi URL from DBBooth.room.jitsi_url (admin-configured) OR _make_jitsi_url(base_url, default_jitsi_room).
  • URL format: {effective_jitsi_base_url}/{room_name} (if room is not already a full URL).
  • Domain passed to template as jitsi_domain (derived from effective_jitsi_base_url).
  • Self-hosted; image: jitsi/*:stable-9823.

Jitsi room naming convention (auto-generated)

When admin creates a room, a Jitsi URL is auto-generated:

clean_name = re.sub(r'[^a-zA-Z0-9]+', '', display_name)
room_id_str = f"Voxbento-{event.slug}-{clean_name}"
jitsi_url = _make_jitsi_url(effective_jitsi_base_url, room_id_str)

Critical: Jitsi is monitoring only

Never use Jitsi's audio as the broadcast source. Interpreter mic → WHIP → MediaMTX is the only valid ingest path.


OpenAI (Transcription)

  • whisper-1: POST https://api.openai.com/v1/audio/transcriptions — WAV file upload per 3-second chunk.
  • gpt-4o-realtime: wss://api.openai.com/v1/realtime?model={model} — WebSocket streaming with PCM frames.
  • Auth: Authorization: Bearer {api_key} header.
  • API key: stored encrypted as events.openai_api_key; requires event.transcription_api_enabled = True.
  • Retry: tenacity, exponential backoff 2–10s, max 3 attempts on 429/5xx.
  • HTTP client: portal.transcription.shared_http_client (shared httpx.AsyncClient).

Deepgram (Transcription)

  • wss://api.deepgram.com/v1/listen?model=nova-2&language={lang}&encoding=linear16&sample_rate=16000&channels=1&interim_results=true&keepalive=true&endpointing=2000&smart_format=true&punctuate=true
  • Auth: Authorization: Token {api_key}.
  • Protocol: WebSocket streaming — send raw PCM, receive JSON transcripts.
  • KeepAlive: sends {"type":"KeepAlive"} every 5 seconds if no audio.
  • API key: events.deepgram_api_key.

NVIDIA Riva (Transcription)

  • Parakeet-RNNT / Parakeet-CTC via Riva gRPC.
  • Requires optional dependency: uv add eventyay-interpretation-portal[nvidia].
  • Function ID configured via settings.nvidia_function_id (from NVIDIA_FUNCTION_ID env var).
  • API key: events.nvidia_api_key.

ElevenLabs (Transcription)

  • scribe_v2 model.
  • API key: events.elevenlabs_api_key.
  • Implementation in portal/transcription/providers/elevenlabs.py.

API Key Security Pattern

All external API keys follow this pattern:

  1. Admin enters key via admin panel form.
  2. Key encrypted via portal.crypto.encrypt_val(key) → stored in DB.
  3. At transcription start: get_api_key(event, ProviderEnum.X) → decrypt_val(encrypted_col).
  4. API_KEY_ENCRYPTION_KEY must be set as env var (≥32 chars); fails loudly if default.
  5. Key rotation: add new key as prefix to comma-separated API_KEY_ENCRYPTION_KEY; MultiFernet tries all keys.

Future Eventyay Integration

Currently there is no live API coupling to Eventyay. The pattern mirrors Eventyay conventions only:

  • Event.slug mirrors Eventyay event slug.
  • Room.eventyay_room_id is a nullable foreign reference (not yet used).
  • Role names match Eventyay role conventions.

When integrating: use portal.* imports; do not couple to pretix.*, pretalx.*, or venueless.*.