Match voice (LiveKit / Mumble)

VAD required, match session API, local E2E and production checklist

Voice API (LiveKit + Murmur)



Laravel orchestrates permissions (friends / match / clan, mute penalties) and issues join credentials.
Redis stores short-lived Mumble passwords and voice-on presence sets.
Audio runs on LiveKit (WebRTC) or Murmur (Mumble protocol) — not through Redis or PHP.

Providers



ProviderClientLaravel returns
livekitLiveKit SDK (Unity/Unreal)url, room_name, token, expires_in
mumbleMumble/Mumla clienthost, port, channel, username, password

Enable in .env: LIVEKIT_ENABLED, MUMBLE_ENABLED (both can be true so the game chooses).

Client requirement: VAD (mandatory)



Games must enable Voice Activity Detection (VAD) on the in-game voice client. The microphone must only send audio when the player exceeds a volume threshold. If players are silent, uplink bandwidth is effectively 0 kbps per silent client.

  • Read the canonical policy from GET /api/v1/voice/config → data.client_requirements.vad (required: true).

  • LiveKit: gate track publish on VAD; do not stream continuous silence.

  • Mumble: use client speech detection; disable continuous transmission.

  • Push-to-talk may be offered in addition, but does not replace VAD for open-mic match voice unless your title is PTT-only by design.


  • Full E2E checklist: MATCH_VOICE_E2E.md.

    Endpoints (/api/v1/voice, Bearer session token)



    MethodPathDescription
    GET/configEnabled providers + client_requirements (VAD)
    POST/rooms/direct{ "friend_user_id": 12 } — 1:1, friends only
    POST/rooms/matchDisabled legacy endpoint (403); use /api/v1/matches with server-issued tickets
    POST/rooms/clan{ "clan_id": 5 } — clan members
    GET/rooms/{id}Room + participants
    POST/rooms/{id}/join{ "provider": "livekit\mumble", "voice_enabled": true }
    POST/rooms/{id}/leaveDisconnect / revoke Mumble password

    join with voice_enabled: false opts out without credentials.

    Flow (match)



    Use the unified match session API — see MATCH_VOICE_E2E.md:

  • 1. Dedicated/matchmaking backend asks the panel to issue a host ticket: POST /api/v1/server/matches/ticket, authenticated with the game's gp_ server secret. JSON: game_id, internal player_id, match_key, team_id: null. Response: join_ticket.

  • 2. Host player: POST /api/v1/matches with the player's Bearer, match_key, join_ticket and optionally member_user_ids: []. Non-empty member lists are rejected. This player endpoint cannot be called using only the server secret.

  • 3. Backend issues a separate ticket for each player's assigned team_id, including the host. Each player calls POST /api/v1/matches/{matchKey}/join with their own Bearer and JSON join_ticket, matching team_id, voice_enabled and voice_provider (required for voice). Create must finish before join.

  • 4. Voice is team-only — one LiveKit/Mumble room per team_id; enemies do not share voice. Connect using data.voice, not the match ticket.

  • 5. Text — two channels: data.text.all (everyone) and data.text.team (after join with team_id).

  • 6. POST /api/v1/matches/{matchKey}/leave on disconnect.


  • No friendship is required for match chat/voice. Access requires a valid player session and a ticket bound to that game, player, match and team. Knowing match_key alone is insufficient. Tickets expire after five minutes and are sent in JSON as join_ticket, not in an extra header or a ticket field. A null-team create ticket cannot authorize a team join.

    The old POST /voice/rooms/match flow is disabled (403). The complete request/response examples and backend/client responsibilities are in the ticket contract.

    Infrastructure



  • LiveKit: self-host (e.g. wss://livekit.idcgames.com) or Cloud; set LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET (must match deploy/livekit.yaml on the voice server).

  • Murmur: run Murmur; optional authenticator can validate Redis passwords later; channel path is MUMBLE_CHANNEL_PREFIX/g{game_id}/....

  • Redis: same REDIS_* as Laravel; keys prefixed with VOICE_REDIS_PREFIX.


  • See also CHAT_API.md for text chat + Reverb.


    ---

    Prueba completa: partida (texto + voz)



    Guía para que un juego integre y pruebe de punta a punta chat de partida (Reverb) y voz (LiveKit o Mumble) contra el Game Panel.

    Documentación relacionada:

  • Texto: CHAT_API.md

  • Voz (API): VOICE_API.md

  • Docker local y producción: VOICE_LOCAL_AND_PRODUCTION.md

  • Postman: colección Extended → carpetas Match Session y Voice


  • ---

    Requisito obligatorio del cliente: VAD



    VAD (Voice Activity Detection) es obligatorio en el cliente del juego.

    Al configurar el micrófono con VAD, el cliente solo envía paquetes de audio cuando el jugador supera un umbral de volumen. Si miles de jugadores están callados, el consumo de subida es efectivamente 0 kbps por jugador silencioso.

  • El panel expone la política en GET /api/v1/voice/config → data.client_requirements.vad.

  • LiveKit: no publiques un track de audio continuo en silencio; abre el gate de publicación cuando VAD detecte voz.

  • Mumble: desactiva transmisión continua; usa detección de voz del cliente.

  • Push-to-talk puede existir como opción extra, pero no sustituye VAD para partidas con micrófono abierto.


  • ---

    API recomendada para partidas



    Contrato de tickets: backend y jugador (verificado 2026-10-19)



    El Game Panel emite y firma el ticket. Lo solicita por S2S el dedicated, matchmaking u orquestador de confianza que tenga el secreto gp_ del juego. Ese backend comprueba previamente qué jugador pertenece a qué partida/equipo y entrega a cada jugador únicamente su ticket. El cliente no recibe el secreto gp_ ni firma tickets.

    OperaciónActor y credencialEndpoint
    Emitir ticketBackend: X-Game-Secret: <gp_del_juego> o game_secret_token en JSONPOST /api/v1/server/matches/ticket
    Crear sesión de chat de partidaJugador anfitrión: Bearer de sesión + ticket sin equipoPOST /api/v1/matches
    Entrar en la partida/equipoCada jugador, incluido el anfitrión: su Bearer + ticket para su equipoPOST /api/v1/matches/{matchKey}/join

    La URL de emisión es /server/matches/ticket, en singular, bajo /api/v1. No existe POST /matches/tickets. El token público gpp_ y el Bearer del jugador no autorizan la emisión S2S.

    No hay un create S2S de partidas en este contrato. El dedicated puede crear la sesión real del juego y decidir su match_key, pero POST /matches del panel exige una sesión de jugador. El backend autoriza a un anfitrión y este hace create con su ticket. Emitir un ticket no crea la partida; join devuelve 404 si nadie la ha creado antes. Un secreto gp_ por sí solo no sustituye al Bearer en create/join.

    #### 1. Backend: ticket de creación del anfitrión

    POST /api/v1/server/matches/ticket
    Content-Type: application/json
    Accept: application/json
    X-Game-Secret:


    {
    "game_id": 1,
    "player_id": 101,
    "match_key": "ranked-4421",
    "team_id": null
    }


    player_id es el ID interno del jugador del panel (user.id del login), no el ID de Steam/Epic/IDC. Debe pertenecer a game_id. match_key admite hasta 128 caracteres y team_id hasta 64; usar valores estables, sin espacios exteriores. Para create, omitir team_id o enviar null: un ticket de equipo no sirve para crear.

    Respuesta HTTP 200:

    {
    "success": true,
    "join_ticket": ""
    }


    El backend entrega este ticket al jugador 101 por su transporte autenticado. Si usa la credencial en JSON en vez del header, añade "game_secret_token": "" al cuerpo S2S. No debe añadir ese campo a las peticiones del cliente.

    #### 2. Anfitrión: crear la sesión del panel

    POST /api/v1/matches
    Authorization: Bearer
    Content-Type: application/json
    Accept: application/json


    {
    "match_key": "ranked-4421",
    "label": "Ranked #4421",
    "member_user_ids": [],
    "join_ticket": ""
    }


    Respuesta HTTP 201: crea el chat All y añade al anfitrión. member_user_ids debe omitirse o ser []; una lista no vacía devuelve 403. El cliente anfitrión no puede autorizar a otros jugadores. create no asigna equipo ni devuelve credenciales de voz.

    #### 3. Backend: ticket individual de entrada y equipo

    Para cada jugador autorizado, llamar otra vez al mismo endpoint S2S:

    {
    "game_id": 1,
    "player_id": 101,
    "match_key": "ranked-4421",
    "team_id": "red"
    }


    Respuesta: {"success": true, "join_ticket": ""}. El anfitrión también necesita este ticket si va a entrar al equipo red; su ticket de creación tiene equipo null y no sirve para un join con team_id: "red". Repetir para el resto con su player_id y equipo autorizado.

    #### 4. Jugador: entrar a chat y voz

    POST /api/v1/matches/ranked-4421/join
    Authorization: Bearer
    Content-Type: application/json
    Accept: application/json


    {
    "join_ticket": "",
    "team_id": "red",
    "voice_enabled": true,
    "voice_provider": "livekit"
    }


    Para Mumble, cambiar voice_provider a mumble. Para probar solo texto de equipo, conservar ticket/equipo y enviar voice_enabled: false; puede omitirse voice_provider. Para solo chat All, emitir un ticket con equipo null y omitir team_id al entrar con voice_enabled: false.

    El campo se llama join_ticket y va en el cuerpo JSON, tanto en create como en join. No se lee un campo ticket ni un header de ticket. Authorization siempre contiene el access token de sesión del jugador, no el ticket ni gp_/gpp_.

    Respuesta HTTP 200: data.text.all y, si hay equipo, data.text.team contienen los IDs de conversaciones. data.voice contiene las credenciales LiveKit/Mumble si se solicita voz y el proveedor está operativo. El ticket de partida no es el JWT de LiveKit: se usa para llamar al panel; la conexión de audio usa después las credenciales de data.voice.

    #### Caducidad, errores y reintentos

  • El ticket está ligado exactamente a juego + jugador + match_key + team_id y caduca a los 5 minutos desde su emisión. Solicitar otro al backend al caducar o volver a conectarse después de ese plazo.

  • La implementación actual no consume el ticket al usarlo: admite reintentos durante su vigencia para la misma combinación. No es un ticket de un solo uso. Un ticket sin equipo puede servir para crear y entrar solo a All con equipo null; no sirve para unirse a red.

  • No compartir tickets entre jugadores ni cambiar el equipo en el cliente. Una asignación de equipo ya establecida en la partida no se cambia mediante otro join.

  • 401: credencial S2S incorrecta en emisión, o sesión de jugador ausente/inválida en create/join.

  • 403: ticket ausente, incorrecto, caducado o para otro jugador/partida/equipo; lista de miembros no vacía; intento de cambiar de equipo; restricciones de comunicación aplicables.

  • 404: jugador inexistente en ese juego al emitir; partida no creada o no accesible al consultar/entrar.

  • 422: campos inválidos; con voz, son obligatorios team_id y voice_provider (livekit o mumble). 503: proveedor de voz no disponible/configuración incompleta.


  • Conocer match_key no basta para entrar. No hace falta amistad entre jugadores. El flujo es el mismo para sandbox y plataformas reales.

    En Postman, la carpeta Match Session (Partida) incluye los pasos S2S - Issue Host Create Ticket y S2S - Issue Player Team Ticket. Configurar game_id, user_id (ID interno), access_token, gamepanel_secret_token y un match_key fijo antes de empezar. La emisión guarda match_create_ticket o match_join_ticket para los pasos siguientes. Al probar otro jugador, cambiar su user_id y access_token y emitir su propio ticket de equipo. Las peticiones S2S son herramientas del backend; no deben trasladarse a una build de jugador.

    La ruta antigua POST /api/v1/voice/rooms/match está deshabilitada y devuelve 403: no usarla como alternativa sin tickets. Usar la API unificada descrita aquí.

    Usa la sesión unificada (mismo match_key que tu servidor de partida):

    PasoMétodoRuta
    0. Backend emite tickets individualesPOST/api/v1/server/matches/ticket
    1. Crear partida (host)POST/api/v1/matches
    2. Estado / participantesGET/api/v1/matches/{matchKey}
    3. Cada jugador entraPOST/api/v1/matches/{matchKey}/join
    4. Mensajes de textoPOST/api/v1/chat/conversations/{id}/messages
    5. Tiempo real textoReverbcanal private-chat.conversation.{id}
    6. SalirPOST/api/v1/matches/{matchKey}/leave

    Body crear partida (sin amistad; match_key = id de sesión del servidor de juego):

    {
    "match_key": "photon-room-uuid-or-session-id",
    "member_user_ids": [],
    "label": "Ranked #4421",
    "join_ticket": ""
    }


    member_user_ids debe omitirse o ser []. Cada jugador entra con su Bearer y su propio join_ticket autorizado por el backend (no hace falta amistad).

    Respuesta incluye dos chats lógicos:

  • data.chat.all — conversación All (toda la partida)

  • data.chat.team — conversación Team (se crea al hacer join con team_id)


  • Body join:

    {
    "join_ticket": "",
    "voice_enabled": true,
    "voice_provider": "livekit",
    "team_id": "red"
    }


  • Texto team: envía mensajes a POST /chat/conversations/{team.conversation_id}/messages (tras join con team_id).

  • Texto all: usa text.all.conversation_id del join.

  • Voz: solo equipo; team_id es obligatorio si voice_enabled es true. Cada equipo obtiene su sala LiveKit/Mumble (livekit_room_name distinto por team_id).


  • voice_provider puede ser livekit o mumble si ambos están habilitados en el servidor.

    Respuesta ejemplo (create)



    {
    "success": true,
    "data": {
    "match_key": "photon-room-uuid",
    "presence_user_ids": [101],
    "chat": {
    "all": {
    "conversation_id": 42,
    "channel": "private-chat.conversation.42",
    "name": "Ranked #4421 (All)"
    },
    "team": null
    },
    "voice": {
    "scope": "team",
    "team_id_required": true,
    "team": null
    }
    }
    }


    Respuesta ejemplo (join con voz)



    {
    "success": true,
    "data": {
    "match_key": "photon-room-uuid",
    "team_id": "red",
    "text": {
    "all": { "conversation_id": 42, "channel": "private-chat.conversation.42" },
    "team": { "conversation_id": 43, "channel": "private-chat.conversation.43" }
    },
    "voice": {
    "voice_enabled": true,
    "url": "wss://livekit.idcgames.com",
    "token": "…",
    "room_name": "g1_match_photon-room-uuid_team_red"
    }
    }
    }


    Amistad vs partida



    ModoAPI¿Amistad?
    DM / grupo de amigos / clan/api/v1/chat/...Sí (excepto clan = miembro de clan)
    Partida (All + Team)/api/v1/matches/...No — Bearer + ticket individual para partida/equipo del mismo juego

    ---

    Checklist local (desarrollo)



    1. Laravel



    composer install
    cp .env.example .env # si aún no existe
    php artisan key:generate
    php artisan migrate


    .env mínimo para esta prueba:

    BROADCAST_CONNECTION=reverb
    REVERB_HOST=127.0.0.1
    REVERB_PORT=8080
    REVERB_SCHEME=http

    REDIS_HOST=127.0.0.1
    REDIS_CLIENT=predis

    LIVEKIT_ENABLED=true
    LIVEKIT_URL=ws://127.0.0.1:7880
    LIVEKIT_API_KEY=devkey
    LIVEKIT_API_SECRET=secret

    MUMBLE_ENABLED=true
    MUMBLE_HOST=127.0.0.1
    MUMBLE_PORT=64738


    En Windows/XAMPP sin extensión phpredis: composer require predis/predis y REDIS_CLIENT=predis. Puedes levantar Redis con el binario portable en tools/redis (redis-server.exe --port 6379 --bind 127.0.0.1).

    2. Procesos (4 terminales)



    TerminalComando
    Aphp artisan serve
    Bphp artisan reverb:start
    CRedis (XAMPP/Memurai/WSL redis-server)
    Ddocker compose -f docker-compose.voice.yml up -d (LiveKit + Murmur)

    Si Docker no está instalado, instala Docker Desktop o despliega LiveKit/Murmur manualmente (ver VOICE_LOCAL_AND_PRODUCTION.md).

    3. Verificación HTTP automática



    Con serve en marcha y Redis disponible:

    php artisan chat:verify-http
    php artisan match:verify-http


    match:verify-http comprueba: crear partida (sin amistad) → join con team_id + credenciales LiveKit → mensaje en chat all → leave.

    Producción:

    php artisan match:verify-http --base-url=https://gamepanel.idcgames.com


    4. Postman (flujo manual)



  • 1. Importar public/downloads/postman/IDCGames_API_Extended.json.

  • 2. Login sandbox (carpeta Auth) → access_token en dos usuarios (no hace falta amistad para partida).

  • 3. Carpeta Match Session: Create Match → Join Match (LiveKit) (incluye team_id) → Send Match Chat Message (usa match_all_conversation_id).

  • 5. Carpeta Voice: Get Voice Config (leer client_requirements.vad).

  • 6. Cliente de juego: conectar Reverb + LiveKit SDK con VAD; o Mumble con detección de voz.


  • 5. Prueba de audio real



  • LiveKit: LiveKit Meet no aplica tokens del panel; usa el SDK en Unity/Unreal con url + token del join.

  • Mumble: cliente desktop a MUMBLE_HOST:MUMBLE_PORT con channel, username, password del JSON de join.


  • ---

    Checklist producción (listo para un juego piloto)



    ComponenteAcción
    LaravelDeploy código, php artisan migrate --force, config:cache
    MySQLTablas chat + voice_rooms
    RedisObligatorio en el servidor del panel (REDIS_HOST=127.0.0.1)
    ReverbSupervisor/systemd; nginx /app + /apps → 127.0.0.1:8082
    LiveKitVPS voz; nginx wss://livekit.idcgames.com → 127.0.0.1:7880; UDP 50000–50100
    Murmurmumble.idcgames.com:64738 (TCP/UDP)
    ClienteVAD obligatorio; leer /voice/config al iniciar sesión de voz

    .env producción (panel — ejemplo IDCGames)



    APP_URL=https://gamepanel.idcgames.com

    BROADCAST_CONNECTION=reverb
    REVERB_HOST=gamepanel.idcgames.com
    REVERB_SCHEME=https
    REVERB_PORT=443
    REVERB_SERVER_HOST=127.0.0.1
    REVERB_SERVER_PORT=8082

    REDIS_HOST=127.0.0.1
    REDIS_CLIENT=predis

    LIVEKIT_ENABLED=true
    LIVEKIT_URL=wss://livekit.idcgames.com
    LIVEKIT_API_KEY=…
    LIVEKIT_API_SECRET=…

    MUMBLE_ENABLED=true
    MUMBLE_HOST=mumble.idcgames.com
    MUMBLE_PORT=64738
    MUMBLE_CHANNEL_PREFIX=idcgames
    MUMBLE_SERVER_NAME="IDCGames Voice"


    LIVEKIT_API_KEY / LIVEKIT_API_SECRET deben ser el mismo par que en deploy/livekit.yaml del servidor LiveKit (generar con docker run --rm livekit/livekit-server generate-keys, no usar devkey/secret en producción).

    Orden de integración sugerido para el estudio:

  • 1. Login IDC → token de sesión.

  • 2. El backend emite ticket sin equipo para el anfitrión; este hace POST /matches con Bearer, match_key y join_ticket.

  • 3. El backend emite tickets con equipo para cada jugador, incluido el anfitrión. Cada cliente hace POST /matches/{key}/join con Bearer, join_ticket y el mismo team_id del ticket → suscribir Reverb a text.all y/o text.team.

  • 4. Si voice_enabled: conectar LiveKit/Mumble con VAD (solo oye/habla su equipo).

  • 5. Fin de partida: leave + desconectar WS/voz.


  • ---

    Tests PHPUnit



    php artisan test --filter=MatchSession
    php artisan test --filter=Voice
    php artisan test --filter=Chat


    Los tests de voz mockean Redis; no sustituyen la prueba con LiveKit/Murmur reales.

    Cliente SDK (Reverb + LiveKit)



    Recomendado: 5 s en LiveKit (audio) + Murmur (TCP) + Reverb


    php artisan match:verify-voice-smoke
    php artisan match:verify-voice-smoke --seconds=5

    php artisan match:verify-sdk
    php artisan match:verify-sdk --players=6 --mumble
    php artisan match:verify-sdk --livekit-audio


    Ver tools/match-e2e-client/README.md.

    Client samples (Unity / Unreal)



    Al integrar los samples o helpers, comprobar que envían join_ticket recibido del backend en create y join. Los ejemplos anteriores a este contrato que solo envían match_key no autorizan la entrada y recibirán 403; no poner gp_ en el cliente para evitarlos.

  • Unity: public/downloads/unity/IDCMatchVoiceManager.cs, IDCMatchVoiceLiveKitBridge.cs

  • Unreal: public/downloads/unreal/IDCVoiceMatchClient.h / .cpp

  • Developer Hub → Unity / Unreal examples