Broadcast

Host Side                                    Viewer Side
=========                                    ===========

[1] POST /api/v1/broadcasts
    Create the broadcast, get token & share_url
         |
[2] Share share_url with viewers ──────────> Receive the share link
         |                                         |
[3] POST /api/v1/auth/ticket                 [A] GET /api/v1/viewer/broadcasts/{token}
    Get the WebSocket Ticket                      Query public broadcast info
         |                                         |
[4] WebSocket connection                      [B] (if password protected)
    wss://vas-poc.vurbo.ai/ws                        POST /viewer/broadcasts/{token}/verify
         |                                         Get viewer_access_token
[5] Send start action                              |
    type: "broadcast"                         [C] EventSource connection
    broadcast_token: "xxx"                        GET /broadcast/{token}/text
    broadcast_phase: "standby"                     |
         |                                         |
    ===== Standby Phase =====                       |
         |                                    Receive connected event
[6] STT/translation results visible           Receive standby event
    to host only                              Show "Preparing, please wait..."
    Host tests the equipment                       |
         |                                         |
    ===== Switch to live phase =====                |
         |                                         |
[7] broadcast_go_live ─────────────────────> Receive phase_changed event
         |                                    phase: "live"
    ===== Live =====                                |
         |                                         |
[8] Send audio (audio action)                [D] Receive live subtitles
    Receive recognition results                   origin event (source text)
    Receive translation results                   translation event (translation)
         |                                         tts_ready event (TTS audio)
         |                                         |
[9] Pause (pause) ─────────────────────────> Receive paused event
         |                                         |
[10] Resume (resume) ──────────────────────> Receive resumed event
         |                                         |
[11] Send announcement ────────────────────> Receive announcement event
         |                                         |
[12] Stop (stop) ──────────────────────────> Receive ended event
                                                   Close the SSE connection

curl -X POST "https://vas-poc.vurbo.ai/api/v1/broadcasts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_language": "zh-TW",
    "translation_languages": ["en-US", "ja-JP"],
    "name": "Tech Seminar Live Subtitles",
    "access_type": "public",
    "max_viewers": 100,
    "speaker_diarization": false,
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "summary_template": "meeting",
    "summary_language": "zh-TW"
  }'

https://vas-poc.vurbo.ai/broadcast/a3f9

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/ticket" \
  -H "X-API-Key: YOUR_API_KEY"

const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "broadcast",
    "broadcast_token": "a3f9",
    "audio_format": "pcm",
    "broadcast_phase": "standby",
    "standby_message": "The talk is about to begin, please wait..."
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "session_started",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "recording_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_type": "broadcast",
    "recognition_mode": "multi_speaker",
    "phase": "standby",
    "viewer_count": 0,
    "queue_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "message": "Speech recognition started"
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "set_standby_message",
    "message": "The presenter is getting ready, expected to start in about 5 minutes..."
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_go_live"
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_phase_changed",
    "phase": "live",
    "message": "Broadcast has started"
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "audio",
    "payload": "Base64-encoded audio data"
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "pause"
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "resume"
  }
}

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/{id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "max_viewers": 200
  }'

{
  "type": "voice-translation",
  "data": {
    "action": "viewer_count",
    "viewer_count": 45,
    "queue_count": 8,
    "peak_viewers": 50,
    "total_viewers": 123
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "stop"
  }
}

curl -X GET "https://vas-poc.vurbo.ai/api/v1/viewer/broadcasts/{token}"

curl -X POST "https://vas-poc.vurbo.ai/api/v1/viewer/broadcasts/{token}/verify" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecret123"}'

{
  "data": {
    "viewer_access_token": "aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vWaB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW",
    "expires_at": "2026-01-04T10:00:00.000Z"
  }
}

const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text'
);

const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text?lang=en-US'
);

const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text?lang=en-US&tts=true'
);

const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text?lang=en-US&viewer_access_token=aB3dE5fG7hI9jK1l...'
);

{
  "session_id": "abc123",
  "source_lang": "zh-TW",
  "subscribed_lang": "en-US",
  "available_langs": ["en-US", "ja-JP"],
  "tts_languages": ["en-US"],
  "phase": "live",
  "recognition_mode": "single",
  "client_id": "client_xyz"
}

{
  "sid": 1,
  "text": "Hello everyone, welcome to today's technical seminar",
  "speaker_id": "0",
  "start_time": "00:05",
  "is_final": true
}

{
  "sid": 1,
  "language": "en-US",
  "text": "Hello everyone, welcome to today's technical seminar",
  "speaker_id": "Royx",
  "is_final": true
}

{
  "sid": 1,
  "language": "en-US",
  "transcript": "Hello everyone, welcome to today's technical seminar",
  "text": "Hello everyone, welcome to today's technical seminar",
  "audio": "Base64EncodedMP3...",
  "format": "mp3",
  "duration_ms": 3200,
  "boundaries": [...]
}

// Switch to Japanese
eventSource.close();
const newEventSource = new EventSource(
  `https://vas-poc.vurbo.ai/broadcast/${token}/text?lang=ja-JP&tts=true`
);

function connectBroadcast(token, lang, enableTts, viewerToken) {
  let url = `https://vas-poc.vurbo.ai/broadcast/${token}/text`;
  const params = new URLSearchParams();
  if (lang) params.set('lang', lang);
  if (enableTts) params.set('tts', 'true');
  if (viewerToken) params.set('viewer_access_token', viewerToken);

  if (params.toString()) url += `?${params.toString()}`;

  const eventSource = new EventSource(url);

  // Connection confirmation
  eventSource.addEventListener('connected', (e) => {
    const data = JSON.parse(e.data);
    console.log(`Connected, available languages: ${data.available_langs.join(', ')}`);
  });

  // Standby phase
  eventSource.addEventListener('standby', (e) => {
    const data = JSON.parse(e.data);
    const msg = data.translations?.[lang] || data.message;
    showWaitingScreen(msg);
  });

  // Phase change
  eventSource.addEventListener('phase_changed', (e) => {
    const data = JSON.parse(e.data);
    if (data.phase === 'live') {
      hideWaitingScreen();
    }
  });

  // Source text
  eventSource.addEventListener('origin', (e) => {
    const data = JSON.parse(e.data);
    displayOriginText(data.sid, data.text, data.speaker_id, data.start_time);
  });

  // Translation
  eventSource.addEventListener('translation', (e) => {
    const data = JSON.parse(e.data);
    displayTranslation(data.sid, data.language, data.text);
  });

  // TTS
  eventSource.addEventListener('tts_ready', (e) => {
    const data = JSON.parse(e.data);
    playTtsAudio(data.audio, data.boundaries, data.text);
  });

  // Pause/resume
  eventSource.addEventListener('paused', (e) => {
    showPausedOverlay();
  });
  eventSource.addEventListener('resumed', (e) => {
    hidePausedOverlay();
  });

  // Announcement
  eventSource.addEventListener('announcement', (e) => {
    const data = JSON.parse(e.data);
    const msg = data.translations?.[lang] || data.message;
    showAnnouncement(msg);
  });

  // End
  eventSource.addEventListener('ended', (e) => {
    const data = JSON.parse(e.data);
    showEndedScreen(data.reason);
    eventSource.close();
  });

  // Kicked
  eventSource.addEventListener('kicked', (e) => {
    showKickedMessage();
    eventSource.close();
  });

  // Queue
  eventSource.addEventListener('queued', (e) => {
    const data = JSON.parse(e.data);
    showQueuePosition(data.position, data.estimated_wait);
  });
  eventSource.addEventListener('admitted', (e) => {
    hideQueueScreen();
  });

  // Error
  eventSource.addEventListener('error', (e) => {
    if (e.data) {
      const error = JSON.parse(e.data);
      handleError(error.error_code, error.message);
    }
    eventSource.close();
  });

  return eventSource;
}

curl -X POST "https://vas-poc.vurbo.ai/api/v1/broadcasts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_language": "zh-TW",
    "translation_languages": ["en-US"],
    "access_type": "password",
    "pass_code": "mySecret123"
  }'

[1] GET /api/v1/viewer/broadcasts/{token}
    ↓ Confirm requires_password: true
[2] Show the password entry screen
    ↓ Viewer enters the password
[3] POST /api/v1/viewer/broadcasts/{token}/verify
    ↓ Get viewer_access_token
[4] SSE connection includes viewer_access_token
    GET /broadcast/{token}/text?viewer_access_token=xxx

# Change to password protected
curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/{id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_type": "password",
    "pass_code": "newPassword"
  }'

# Change back to public
curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/{id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_type": "public"
  }'

{
  "position": 3,
  "estimated_wait": "About 2 minutes"
}

{
  "message": "You have entered the broadcast"
}

{
  "reason": "capacity_exceeded",
  "duration_ms": 0
}

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/{id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_viewers": 200}'

pending  ──(WebSocket start)──>  active  ──(pause)──>  paused
                                   |                      |
                                   |    <──(resume)───────
                                   |
                                   ├──(stop)──>  ended
                                   |
pending  ──(DELETE)──>  revoked

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "broadcast",
    "broadcast_token": "YOUR_TOKEN",
    "audio_format": "pcm",
    "broadcast_phase": "standby",
    "standby_message": "The talk is about to begin, please wait..."
  }
}

{
  "type": "voice-translation",
  "data": {
    "action": "set_standby_message",
    "message": "Adjusting the equipment, expected to start in 3 minutes"
  }
}

event: standby
data: {"message":"Adjusting the equipment, expected to start in 3 minutes","translations":{"en-US":"Adjusting equipment, expected to start in 3 minutes","ja-JP":"機器の調整中、約3分後に開始予定"}}

eventSource.addEventListener('standby', (e) => {
  const data = JSON.parse(e.data);
  // Display the corresponding translation based on the viewer's selected language
  const displayLang = 'en-US';
  const msg = data.translations?.[displayLang] || data.message;
  showWaitingScreen(msg);
});

eventSource.addEventListener('phase_changed', (e) => {
  const data = JSON.parse(e.data);
  if (data.phase === 'live') {
    hideWaitingScreen();
    // Start displaying the subtitle area
  }
});

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_announcement",
    "message": "The meeting will end in 5 minutes"
  }
}

{
  "message": "The meeting will end in 5 minutes",
  "translations": {
    "en-US": "The meeting will end in 5 minutes",
    "ja-JP": "会議は5分後に終了します"
  }
}

eventSource.addEventListener('announcement', (e) => {
  const data = JSON.parse(e.data);
  const displayLang = 'en-US';
  const msg = data.translations?.[displayLang] || data.message;
  showAnnouncementPopup(msg);
});