Provider Analysis

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

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 portal/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.*.