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
| Provider | Client | Laravel returns |
|---|---|---|
livekit | LiveKit SDK (Unity/Unreal) | url, room_name, token, expires_in |
mumble | Mumble/Mumla client | host, 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.
- 1. Dedicated/matchmaking backend asks the panel to issue a host ticket:
POST /api/v1/server/matches/ticket, authenticated with the game'sgp_server secret. JSON:game_id, internalplayer_id,match_key,team_id: null. Response:join_ticket. - 2. Host player:
POST /api/v1/matcheswith the player's Bearer,match_key,join_ticketand optionallymember_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 callsPOST /api/v1/matches/{matchKey}/joinwith their own Bearer and JSONjoin_ticket, matchingteam_id,voice_enabledandvoice_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 usingdata.voice, not the match ticket. - 5. Text — two channels:
data.text.all(everyone) anddata.text.team(after join withteam_id). - 6.
POST /api/v1/matches/{matchKey}/leaveon disconnect. - LiveKit: self-host (e.g.
wss://livekit.idcgames.com) or Cloud; setLIVEKIT_URL,LIVEKIT_API_KEY,LIVEKIT_API_SECRET(must matchdeploy/livekit.yamlon 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 withVOICE_REDIS_PREFIX. - 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
- 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.
Full E2E checklist: MATCH_VOICE_E2E.md.
Endpoints (/api/v1/voice, Bearer session token)
| Method | Path | Description | |
|---|---|---|---|
| GET | /config | Enabled providers + client_requirements (VAD) | |
| POST | /rooms/direct | { "friend_user_id": 12 } — 1:1, friends only | |
| POST | /rooms/match | Disabled 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}/leave | Disconnect / 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:
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
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:
---
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.
---
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ón | Actor y credencial | Endpoint |
|---|---|---|
| Emitir ticket | Backend: X-Game-Secret: <gp_del_juego> o game_secret_token en JSON | POST /api/v1/server/matches/ticket |
| Crear sesión de chat de partida | Jugador anfitrión: Bearer de sesión + ticket sin equipo | POST /api/v1/matches |
| Entrar en la partida/equipo | Cada jugador, incluido el anfitrión: su Bearer + ticket para su equipo | POST /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
null; no sirve para unirse a red.join.create/join.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):| Paso | Método | Ruta |
|---|---|---|
| 0. Backend emite tickets individuales | POST | /api/v1/server/matches/ticket |
| 1. Crear partida (host) | POST | /api/v1/matches |
| 2. Estado / participantes | GET | /api/v1/matches/{matchKey} |
| 3. Cada jugador entra | POST | /api/v1/matches/{matchKey}/join |
| 4. Mensajes de texto | POST | /api/v1/chat/conversations/{id}/messages |
| 5. Tiempo real texto | Reverb | canal private-chat.conversation.{id} |
| 6. Salir | POST | /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"
} POST /chat/conversations/{team.conversation_id}/messages (tras join con team_id).text.all.conversation_id del join.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
| Modo | API | ¿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=64738En 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)
| Terminal | Comando |
|---|---|
| A | php artisan serve |
| B | php artisan reverb:start |
| C | Redis (XAMPP/Memurai/WSL redis-server) |
| D | docker 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-httpmatch: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.com4. Postman (flujo manual)
public/downloads/postman/IDCGames_API_Extended.json.access_token en dos usuarios (no hace falta amistad para partida).team_id) → Send Match Chat Message (usa match_all_conversation_id).client_requirements.vad).5. Prueba de audio real
url + token del join.MUMBLE_HOST:MUMBLE_PORT con channel, username, password del JSON de join.---
Checklist producción (listo para un juego piloto)
| Componente | Acción |
|---|---|
| Laravel | Deploy código, php artisan migrate --force, config:cache |
| MySQL | Tablas chat + voice_rooms |
| Redis | Obligatorio en el servidor del panel (REDIS_HOST=127.0.0.1) |
| Reverb | Supervisor/systemd; nginx /app + /apps → 127.0.0.1:8082 |
| LiveKit | VPS voz; nginx wss://livekit.idcgames.com → 127.0.0.1:7880; UDP 50000–50100 |
| Murmur | mumble.idcgames.com:64738 (TCP/UDP) |
| Cliente | VAD 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:
POST /matches con Bearer, match_key y join_ticket.POST /matches/{key}/join con Bearer, join_ticket y el mismo team_id del ticket → suscribir Reverb a text.all y/o text.team.voice_enabled: conectar LiveKit/Mumble con VAD (solo oye/habla su equipo).leave + desconectar WS/voz.---
Tests PHPUnit
php artisan test --filter=MatchSession
php artisan test --filter=Voice
php artisan test --filter=ChatLos 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-audioVer
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.public/downloads/unity/IDCMatchVoiceManager.cs, IDCMatchVoiceLiveKitBridge.cspublic/downloads/unreal/IDCVoiceMatchClient.h / .cpp