[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78263619QAFGCJBHFNT4S9B":3,"skill-same:01M78263619QAFGCJBHFNT4S9B":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M78263619QAFGCJBHFNT4S9B","debug-voice",null,"Use when the user runs \u002Fdebug-voice, says voice mode has flaws, asks to see or capture what happened in a Grok realtime voice session, or a voice integration has no debug logging yet. Proposes a plan, then installs a dev-only log pipeline (client logger → local NDJSON) in the app's own language and conventions, then runs the fix loop: match the user's report to log signatures, fix one thing, re-test.","TheAngryPit\u002FTheAngrySkills","TheAngryPit","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7040636?v=4","01M7803EENA9ATXJ46S9268QJX","Vitor Cepeda Lopes","01M7803EF9FMF4G4420XE4DV7Y",0,"MIT","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fgrok-voice\u002Fskills\u002Fdebug-voice\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: debug-voice\ndescription: >-\n  Use when the user runs \u002Fdebug-voice, says voice mode has flaws, asks to see or\n  capture what happened in a Grok realtime voice session, or a voice integration\n  has no debug logging yet. Proposes a plan, then installs a dev-only log\n  pipeline (client logger → local NDJSON) in the app's own language and\n  conventions, then runs the fix loop: match the user's report to log\n  signatures, fix one thing, re-test.\n---\n\n# Debug Voice\n\nMake a voice session readable after the fact, then fix from evidence. The agent cannot hear the app; the log is its ears, the user is its judge. No audio, no tokens, never in prod.\n\nWorks for any stack. The pipeline is a small contract (below); implement it in whatever the app already uses.\n\n## Workflow\n\n1. **Map** the app (read only).\n2. **Plan**: write the change list, show it, **stop**. Nothing is edited until the user aligns.\n3. **Install** the agreed pieces in the app's language, framework, and conventions.\n4. **Verify** the sink, hand the app to the user.\n5. **Fix loop** from the log.\n\n## 1. Map\n\nFind, and note the paths:\n\n- Voice client: where realtime events are received and sent, mic capture, audio playback, token fetch.\n- Server: framework, how routes are declared, where shared server code lives, how env is read, what \"production\" means here.\n- Conventions: language(s), module system, formatter, where scripts or tasks live (`package.json`, `Makefile`, `pyproject`, `justfile`), `.gitignore`.\n- Client kind: browser, mobile, desktop, CLI. A non-browser client still POSTs the same JSON; a single-process app can skip HTTP and append to the file directly.\n- Where audio deltas are handled. They must be counted, never logged.\n\n## 2. Plan, then stop\n\nFill this in with real paths and the app's language, post it, and wait for a yes or a trimmed list. Do not edit files before that.\n\n```markdown\n## Debug voice: plan\n\nAdd\n- \u003Cpath>: client logger (batch, redact, flush) in \u003Clanguage>\n- \u003Cpath>: dev-only sink `POST \u002Fapi\u002Fvoice\u002Flog` → `.voice-logs\u002F\u003CsessionId>.ndjson`\n- \u003Cpath> (optional): summary command `\u003Ccmd>`; otherwise read the NDJSON with jq\n\nModify\n- \u003Cvoice client file>: hook points start, token, mic, env, ws.*, client\u002Fserver events,\n  audio.in (2 s windows), audio.out.first, audio.out, play.stop, stop\n- \u003Ctoken route>: append `server.token { ok, status, ms, upstream }` (never the token)\n- \u003CUI file>: session id in the voice status line and in voice error messages\n- .gitignore: `\u002F.voice-logs`\n- \u003Cscripts file>: a `voice:logs` task (only if the summary command is wanted)\n\nLogged: event names and non-audio fields, timings, byte counts, mic RMS.\nNever: tokens, API keys, raw audio, strings over 400 chars.\nOff in production unless `VOICE_LOG=1`.\n\nReply \"go\", or strike lines you do not want.\n```\n\n## 3. Install: the contract\n\nMatch the app. Same language as the surrounding code, same route style, same formatter. Write the pieces from the contract below; do not introduce a second language or toolchain for logging.\n\n**Session id**: 8 lowercase hex chars from a UUID. The sink accepts `^[a-z0-9]{4,64}$`; it becomes a file name.\n\n**Entry** (one JSON object per line):\n\n| Field | Client | Server |\n| --- | --- | --- |\n| `t` | ms since the logger started | absent; the reader aligns by `ts` |\n| `ts` | epoch ms | epoch ms |\n| `kind` | `start`, `server`, `client`, `error`, `audio.in`, … | `server.token`, … |\n| `src` | absent | `\"server\"` |\n| rest | the hook's fields, redacted | the hook's fields |\n\n**Redaction, applied client side before buffering**: on audio event types (`response.output_audio.delta`, `response.audio.delta`, `input_audio_buffer.append`) replace `delta` \u002F `audio` with `bytes` = decoded base64 length; strings over 400 chars cut to 400 + `…[N chars]`; objects deeper than 4 → `\"[depth]\"`; arrays over 50 items truncated.\n\n**Client logger**: buffer entries; flush as `POST \u003Csink> {\"sessionId\",\"entries\":[…]}` every 1 s or at 200 entries; on stop flush with keepalive (or the platform's \"survive navigation\" equivalent); swallow every transport error, logging must never throw into the voice path. Also mirror entries to the console in dev.\n\n**Sink**: `POST \u002Fapi\u002Fvoice\u002Flog`, JSON body. `404` unless dev or `VOICE_LOG=1`. `400` if `sessionId` fails the regex or `entries` is not an array. Append at most 500 entries per request, drop any line over 16,000 chars, to `.voice-logs\u002F\u003CsessionId>.ndjson`, creating the directory. Reply `204`.\n\nPseudocode for any server:\n\n```\nhandle POST \u002Fapi\u002Fvoice\u002Flog:\n  if production and VOICE_LOG != \"1\": return 404\n  body = parse json or return 400\n  if not regex(body.sessionId) or not list(body.entries): return 400\n  mkdir .voice-logs; append join(json(e) for e in body.entries[:500] if len \u003C 16000) to .voice-logs\u002F{sessionId}.ndjson\n  return 204\n```\n\nPseudocode for the client logger:\n\n```\nlogger(sessionId, sink):\n  buffer = []; started = now()\n  log(kind, data): buffer.push({ ...redact(data), t: now() - started, ts: epoch_ms(), kind }); schedule flush (1 s timer, or immediately at 200 entries)\n  server(event, extra): log(\"server\", { ...redact_event(event), ...extra })   # never per audio delta\n  client(event):        log(\"client\", redact_event(event))                    # never per audio chunk\n  error(where, err, extra): log(\"error\", { where, name, message, ...extra })\n  flush(final=false): POST sink {\"sessionId\",\"entries\": buffer}; buffer = []; ignore all errors; keepalive when final\n  close(): flush(final=true)\n```\n\n## Hook points\n\n`kind` and fields; the shape is the same in every language.\n\n| When | `kind` and fields |\n| --- | --- |\n| Session start | `start { url, target_rate }` |\n| Token fetched \u002F failed | `token.ok { ms }` \u002F `error { where: \"token\", name, message, ms }` |\n| Mic granted \u002F denied | `mic.ok { ms, label, settings }` \u002F `error { where: \"mic\", … }` |\n| Audio graph ready | `env { ua, mic_rate, mic_state, play_rate, play_state, capture_frames, target_rate }` |\n| Socket | `ws.connecting`, `ws.open { ms }`, `ws.error`, `ws.close { code, reason, wasClean, by }` |\n| Every event sent, except audio chunks | `client { …redacted event }` |\n| Every event received, except audio deltas | `server { …redacted event, phase }` |\n| Phase change (dedupe) | `phase { phase }` |\n| Mic chunks, aggregated per 2 s | `audio.in { chunks, bytes, rms_max, rms_avg, pending, mic_state, phase }` |\n| Pre-open buffer sent on open | `audio.flush { chunks }` |\n| First audio delta of a response | `audio.out.first { response_id, bytes, since_response_created_ms, since_speech_stopped_ms, play_state }` |\n| `response.done` | `audio.out { response_id, status, deltas, bytes, audio_ms, wall_ms, max_gap_ms, queued_ms, underruns, drain_ms_max }` |\n| Barge-in stop | `play.stop { reason, dropped_ms }` |\n| User stop | `stop { by: \"client\", phase }`, then flush |\n| Token route (server) | `server.token { ok, status, ms, upstream }` |\n\nIn the message handler: if the event is an audio delta, count bytes and gaps and play it; otherwise log it as `server` with the current phase, then run the existing handling. Keep `speechStoppedT` from `input_audio_buffer.speech_stopped` and `createdT` from `response.created`; report both distances on the first delta. In the player, count an underrun when the next scheduled time is already in the past mid-response, track the largest drain, reset on `response.created`.\n\nUI: show the id in the voice status line (`Listening · session ab12cd34`) and append `(voice session \u003Cid>)` to voice errors, so the user can name the run.\n\n## 4. Verify\n\n```bash\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\\n\" -X POST localhost:\u003Cport>\u002Fapi\u002Fvoice\u002Flog \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"sessionId\":\"smoke001\",\"entries\":[{\"t\":0,\"ts\":0,\"kind\":\"start\"}]}'   # 204\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\\n\" -X POST localhost:\u003Cport>\u002Fapi\u002Fvoice\u002Flog \\\n  -H 'Content-Type: application\u002Fjson' -d '{\"sessionId\":\"..\u002Fx\",\"entries\":[]}' # 400\ncat .voice-logs\u002Fsmoke001.ndjson && rm .voice-logs\u002Fsmoke001.ndjson\n```\n\nThen hand off: the user tests in the real app and reports what they said, what they heard, when it went wrong, and the session id.\n\n## Reading a log\n\nAny of these; none needs the app's toolchain:\n\n```bash\nf=.voice-logs\u002F\u003Cid>.ndjson\njq -r 'select(.kind|IN(\"start\",\"token.ok\",\"mic.ok\",\"env\",\"ws.open\",\"ws.close\",\"server.token\",\"stop\",\"error\")) | \"\\(.t \u002F\u002F .ts)ms \\(.kind) \\(.type \u002F\u002F \"\") \\(.message \u002F\u002F \"\")\"' $f   # milestones and errors\njq -r 'select(.kind==\"server\") | .type' $f | sort | uniq -c | sort -rn                      # server event counts\njq -c 'select(.kind|IN(\"audio.out.first\",\"audio.out\"))' $f                                  # per-turn latency, gaps, underruns\njq -c 'select(.kind==\"audio.in\")' $f                                                        # mic windows, rms\n```\n\nOr read the file; it is one object per line in time order. Server entries have only `ts`; align them to the client clock with the `start` entry's `ts`. If the user wants a summary command, write one in the app's language that prints: milestones, server event counts, one line per `audio.out` turn with its `audio.out.first` latencies, mic window totals, errors and closes, and the last 25 entries.\n\n## 5. Fix loop\n\n1. **Instrument** (steps 1–4) if the app has no `.voice-logs` pipeline yet.\n2. **User tests** in the real app and describes the run.\n3. **Read the log** around the failing `t`.\n4. **Match** symptom → signature → fix (table below). No matching signature: add logging first, re-test, then fix.\n5. **Fix one thing**, re-test, confirm the signature is gone in a fresh log.\n6. **Write it down**: append a confirmed row under \"Confirmed from sessions\". If the fix changes how voice should be built, update `\u002Fadd-voice` too.\n\n## Symptom → log signature → fix (starter rows)\n\n| Symptom (user) | Signature (log) | Fix |\n| --- | --- | --- |\n| Silence, but transcript appears | `env.play_state` or `audio.out.first.play_state` = `suspended` | Create and resume the playback audio context inside the user gesture; one context per session, not per turn |\n| Assistant interrupts itself | `speech_started` with `phase=speaking`; `audio.in.rms_max` rises only during playback | Echo. Confirm with headphones (if it stops, it is echo). Keep echo cancellation on, lower speaker volume, or gate mic sends while `speaking` |\n| Choppy, stuttering | `audio.out.underruns` > 0, `drain_ms_max` high, `max_gap_ms` far above chunk length | Schedule a small lead (150–250 ms) before the first chunk plays; do not rebuild the audio context per turn |\n| Crackle, wrong pitch or speed | `session.update` rate ≠ buffer rate; odd `bytes` | One rate everywhere (`audio.input\u002Foutput.format.rate`, player buffer); even-byte alignment |\n| Never connects, or closes at once | `ws.close` before `session.updated`; `server.token.ok=false` | Mint a token per click (300 s), protocol `xai-client-secret.\u003Ctoken>`, `model` in URL; read `server.token.status` and `upstream` |\n| Mic does nothing | `audio.in.rms_max` ≈ 0 in every window; `mic.ok.label` unexpected | Wrong device or OS permission; check `mic.ok.settings`, `label`, `mic_state` |\n| No user transcript | no `conversation.item.input_audio_transcription.updated` | Set `audio.input.transcription.model: \"grok-transcribe\"` in `session.update` |\n| Slow first word | `audio.out.first.since_speech_stopped_ms` high | Try `reasoning.effort: \"none\"`; shorter `instructions`; check `token.ok.ms` and `ws.open.ms` for connect cost |\n| User text appears after the reply | `...transcription.updated` `t` > `response.created` `t` | Create the user row on `input_audio_buffer.committed` (`item_id`), fill it on `updated` |\n| First words cut off | `ws.open.ms` large and `audio.flush.chunks` at the buffer cap | Start mic before the socket, buffer early audio, raise the pre-open cap |\n\n## Confirmed from sessions\n\nAppend after a fix is verified in a fresh log. Format: `YYYY-MM-DD · symptom · signature · fix · file(s)`.\n\n## Rules\n\n- Plan first; no edits before the user aligns on the change list.\n- Never tokens, keys, or raw audio. Audio becomes byte counts.\n- Dev only. The sink returns 404 in production unless `VOICE_LOG=1`. `.voice-logs\u002F` is gitignored.\n- Logging never throws into the voice path.\n- Aggregate audio; never log per chunk.\n- One change per re-test so the log tells you which fix worked.\n- Do not invent xAI event names; confirm in https:\u002F\u002Fdocs.x.ai\u002Fdevelopers\u002Fmodel-capabilities\u002Faudio\u002Fspeech-to-speech before adding a signature.\n","# Debug Voice\n\nMake a voice session readable after the fact, then fix from evidence. The agent cannot hear the app; the log is its ears, the user is its judge. No audio, no tokens, never in prod.\n\nWorks for any stack. The pipeline is a small contract (below); implement it in whatever the app already uses.\n\n## Workflow\n\n1. **Map** the app (read only).\n2. **Plan**: write the change list, show it, **stop**. Nothing is edited until the user aligns.\n3. **Install** the agreed pieces in the app's language, framework, and conventions.\n4. **Verify** the sink, hand the app to the user.\n5. **Fix loop** from the log.\n\n## 1. Map\n\nFind, and note the paths:\n\n- Voice client: where realtime events are received and sent, mic capture, audio playback, token fetch.\n- Server: framework, how routes are declared, where shared server code lives, how env is read, what \"production\" means here.\n- Conventions: language(s), module system, formatter, where scripts or tasks live (`package.json`, `Makefile`, `pyproject`, `justfile`), `.gitignore`.\n- Client kind: browser, mobile, desktop, CLI. A non-browser client still POSTs the same JSON; a single-process app can skip HTTP and append to the file directly.\n- Where audio deltas are handled. They must be counted, never logged.\n\n## 2. Plan, then stop\n\nFill this in with real paths and the app's language, post it, and wait for a yes or a trimmed list. Do not edit files before that.\n\n```markdown\n## Debug voice: plan\n\nAdd\n- \u003Cpath>: client logger (batch, redact, flush) in \u003Clanguage>\n- \u003Cpath>: dev-only sink `POST \u002Fapi\u002Fvoice\u002Flog` → `.voice-logs\u002F\u003CsessionId>.ndjson`\n- \u003Cpath> (optional): summary command `\u003Ccmd>`; otherwise read the NDJSON with jq\n\nModify\n- \u003Cvoice client file>: hook points start, token, mic, env, ws.*, client\u002Fserver events,\n  audio.in (2 s windows), audio.out.first, audio.out, play.stop, stop\n- \u003Ctoken route>: append `server.token { ok, status, ms, upstream }` (never the token)\n- \u003CUI file>: session id in the voice status line and in voice error messages\n- .gitignore: `\u002F.voice-logs`\n- \u003Cscripts file>: a `voice:logs` task (only if the summary command is wanted)\n\nLogged: event names and non-audio fields, timings, byte counts, mic RMS.\nNever: tokens, API keys, raw audio, strings over 400 chars.\nOff in production unless `VOICE_LOG=1`.\n\nReply \"go\", or strike lines you do not want.\n```\n\n## 3. Install: the contract\n\nMatch the app. Same language as the surrounding code, same route style, same formatter. Write the pieces from the contract below; do not introduce a second language or toolchain for logging.\n\n**Session id**: 8 lowercase hex chars from a UUID. The sink accepts `^[a-z0-9]{4,64}$`; it becomes a file name.\n\n**Entry** (one JSON object per line):\n\n| Field | Client | Server |\n| --- | --- | --- |\n| `t` | ms since the logger started | absent; the reader aligns by `ts` |\n| `ts` | epoch ms | epoch ms |\n| `kind` | `start`, `server`, `client`, `error`, `audio.in`, … | `server.token`, … |\n| `src` | absent | `\"server\"` |\n| rest | the hook's fields, redacted | the hook's fields |\n\n**Redaction, applied client side before buffering**: on audio event types (`response.output_audio.delta`, `response.audio.delta`, `input_audio_buffer.append`) replace `delta` \u002F `audio` with `bytes` = decoded base64 length; strings over 400 chars cut to 400 + `…[N chars]`; objects deeper than 4 → `\"[depth]\"`; arrays over 50 items truncated.\n\n**Client logger**: buffer entries; flush as `POST \u003Csink> {\"sessionId\",\"entries\":[…]}` every 1 s or at 200 entries; on stop flush with keepalive (or the platform's \"survive navigation\" equivalent); swallow every transport error, logging must never throw into the voice path. Also mirror entries to the console in dev.\n\n**Sink**: `POST \u002Fapi\u002Fvoice\u002Flog`, JSON body. `404` unless dev or `VOICE_LOG=1`. `400` if `sessionId` fails the regex or `entries` is not an array. Append at most 500 entries per request, drop any line over 16,000 chars, to `.voice-logs\u002F\u003CsessionId>.ndjson`, creating the directory. Reply `204`.\n\nPseudocode for any server:\n\n```\nhandle POST \u002Fapi\u002Fvoice\u002Flog:\n  if production and VOICE_LOG != \"1\": return 404\n  body = parse json or return 400\n  if not regex(body.sessionId) or not list(body.entries): return 400\n  mkdir .voice-logs; append join(json(e) for e in body.entries[:500] if len \u003C 16000) to .voice-logs\u002F{sessionId}.ndjson\n  return 204\n```\n\nPseudocode for the client logger:\n\n```\nlogger(sessionId, sink):\n  buffer = []; started = now()\n  log(kind, data): buffer.push({ ...redact(data), t: now() - started, ts: epoch_ms(), kind }); schedule flush (1 s timer, or immediately at 200 entries)\n  server(event, extra): log(\"server\", { ...redact_event(event), ...extra })   # never per audio delta\n  client(event):        log(\"client\", redact_event(event))                    # never per audio chunk\n  error(where, err, extra): log(\"error\", { where, name, message, ...extra })\n  flush(final=false): POST sink {\"sessionId\",\"entries\": buffer}; buffer = []; ignore all errors; keepalive when final\n  close(): flush(final=true)\n```\n\n## Hook points\n\n`kind` and fields; the shape is the same in every language.\n\n| When | `kind` and fields |\n| --- | --- |\n| Session start | `start { url, target_rate }` |\n| Token fetched \u002F failed | `token.ok { ms }` \u002F `error { where: \"token\", name, message, ms }` |\n| Mic granted \u002F denied | `mic.ok { ms, label, settings }` \u002F `error { where: \"mic\", … }` |\n| Audio graph ready | `env { ua, mic_rate, mic_state, play_rate, play_state, capture_frames, target_rate }` |\n| Socket | `ws.connecting`, `ws.open { ms }`, `ws.error`, `ws.close { code, reason, wasClean, by }` |\n| Every event sent, except audio chunks | `client { …redacted event }` |\n| Every event received, except audio deltas | `server { …redacted event, phase }` |\n| Phase change (dedupe) | `phase { phase }` |\n| Mic chunks, aggregated per 2 s | `audio.in { chunks, bytes, rms_max, rms_avg, pending, mic_state, phase }` |\n| Pre-open buffer sent on open | `audio.flush { chunks }` |\n| First audio delta of a response | `audio.out.first { response_id, bytes, since_response_created_ms, since_speech_stopped_ms, play_state }` |\n| `response.done` | `audio.out { response_id, status, deltas, bytes, audio_ms, wall_ms, max_gap_ms, queued_ms, underruns, drain_ms_max }` |\n| Barge-in stop | `play.stop { reason, dropped_ms }` |\n| User stop | `stop { by: \"client\", phase }`, then flush |\n| Token route (server) | `server.token { ok, status, ms, upstream }` |\n\nIn the message handler: if the event is an audio delta, count bytes and gaps and play it; otherwise log it as `server` with the current phase, then run the existing handling. Keep `speechStoppedT` from `input_audio_buffer.speech_stopped` and `createdT` from `response.created`; report both distances on the first delta. In the player, count an underrun when the next scheduled time is already in the past mid-response, track the largest drain, reset on `response.created`.\n\nUI: show the id in the voice status line (`Listening · session ab12cd34`) and append `(voice session \u003Cid>)` to voice errors, so the user can name the run.\n\n## 4. Verify\n\n```bash\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\\n\" -X POST localhost:\u003Cport>\u002Fapi\u002Fvoice\u002Flog \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"sessionId\":\"smoke001\",\"entries\":[{\"t\":0,\"ts\":0,\"kind\":\"start\"}]}'   # 204\ncurl -s -o \u002Fdev\u002Fnull -w \"%{http_code}\\n\" -X POST localhost:\u003Cport>\u002Fapi\u002Fvoice\u002Flog \\\n  -H 'Content-Type: application\u002Fjson' -d '{\"sessionId\":\"..\u002Fx\",\"entries\":[]}' # 400\ncat .voice-logs\u002Fsmoke001.ndjson && rm .voice-logs\u002Fsmoke001.ndjson\n```\n\nThen hand off: the user tests in the real app and reports what they said, what they heard, when it went wrong, and the session id.\n\n## Reading a log\n\nAny of these; none needs the app's toolchain:\n\n```bash\nf=.voice-logs\u002F\u003Cid>.ndjson\njq -r 'select(.kind|IN(\"start\",\"token.ok\",\"mic.ok\",\"env\",\"ws.open\",\"ws.close\",\"server.token\",\"stop\",\"error\")) | \"\\(.t \u002F\u002F .ts)ms \\(.kind) \\(.type \u002F\u002F \"\") \\(.message \u002F\u002F \"\")\"' $f   # milestones and errors\njq -r 'select(.kind==\"server\") | .type' $f | sort | uniq -c | sort -rn                      # server event counts\njq -c 'select(.kind|IN(\"audio.out.first\",\"audio.out\"))' $f                                  # per-turn latency, gaps, underruns\njq -c 'select(.kind==\"audio.in\")' $f                                                        # mic windows, rms\n```\n\nOr read the file; it is one object per line in time order. Server entries have only `ts`; align them to the client clock with the `start` entry's `ts`. If the user wants a summary command, write one in the app's language that prints: milestones, server event counts, one line per `audio.out` turn with its `audio.out.first` latencies, mic window totals, errors and closes, and the last 25 entries.\n\n## 5. Fix loop\n\n1. **Instrument** (steps 1–4) if the app has no `.voice-logs` pipeline yet.\n2. **User tests** in the real app and describes the run.\n3. **Read the log** around the failing `t`.\n4. **Match** symptom → signature → fix (table below). No matching signature: add logging first, re-test, then fix.\n5. **Fix one thing**, re-test, confirm the signature is gone in a fresh log.\n6. **Write it down**: append a confirmed row under \"Confirmed from sessions\". If the fix changes how voice should be built, update `\u002Fadd-voice` too.\n\n## Symptom → log signature → fix (starter rows)\n\n| Symptom (user) | Signature (log) | Fix |\n| --- | --- | --- |\n| Silence, but transcript appears | `env.play_state` or `audio.out.first.play_state` = `suspended` | Create and resume the playback audio context inside the user gesture; one context per session, not per turn |\n| Assistant interrupts itself | `speech_started` with `phase=speaking`; `audio.in.rms_max` rises only during playback | Echo. Confirm with headphones (if it stops, it is echo). Keep echo cancellation on, lower speaker volume, or gate mic sends while `speaking` |\n| Choppy, stuttering | `audio.out.underruns` > 0, `drain_ms_max` high, `max_gap_ms` far above chunk length | Schedule a small lead (150–250 ms) before the first chunk plays; do not rebuild the audio context per turn |\n| Crackle, wrong pitch or speed | `session.update` rate ≠ buffer rate; odd `bytes` | One rate everywhere (`audio.input\u002Foutput.format.rate`, player buffer); even-byte alignment |\n| Never connects, or closes at once | `ws.close` before `session.updated`; `server.token.ok=false` | Mint a token per click (300 s), protocol `xai-client-secret.\u003Ctoken>`, `model` in URL; read `server.token.status` and `upstream` |\n| Mic does nothing | `audio.in.rms_max` ≈ 0 in every window; `mic.ok.label` unexpected | Wrong device or OS permission; check `mic.ok.settings`, `label`, `mic_state` |\n| No user transcript | no `conversation.item.input_audio_transcription.updated` | Set `audio.input.transcription.model: \"grok-transcribe\"` in `session.update` |\n| Slow first word | `audio.out.first.since_speech_stopped_ms` high | Try `reasoning.effort: \"none\"`; shorter `instructions`; check `token.ok.ms` and `ws.open.ms` for connect cost |\n| User text appears after the reply | `...transcription.updated` `t` > `response.created` `t` | Create the user row on `input_audio_buffer.committed` (`item_id`), fill it on `updated` |\n| First words cut off | `ws.open.ms` large and `audio.flush.chunks` at the buffer cap | Start mic before the socket, buffer early audio, raise the pre-open cap |\n\n## Confirmed from sessions\n\nAppend after a fix is verified in a fresh log. Format: `YYYY-MM-DD · symptom · signature · fix · file(s)`.\n\n## Rules\n\n- Plan first; no edits before the user aligns on the change list.\n- Never tokens, keys, or raw audio. Audio becomes byte counts.\n- Dev only. The sink returns 404 in production unless `VOICE_LOG=1`. `.voice-logs\u002F` is gitignored.\n- Logging never throws into the voice path.\n- Aggregate audio; never log per chunk.\n- One change per re-test so the log tells you which fix worked.\n- Do not invent xAI event names; confirm in https:\u002F\u002Fdocs.x.ai\u002Fdevelopers\u002Fmodel-capabilities\u002Faudio\u002Fspeech-to-speech before adding a signature.\n",{"name":5,"description":7},"main","f31e1d2df163b90a48e30d0a3df67285f6641418","sources\u002Fcursor-plugins\u002Fupstream-tree\u002Fgrok-voice\u002Fskills\u002Fdebug-voice",1,"https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills","https:\u002F\u002Fgithub.com\u002FTheAngryPit","www.vitorcepedalopes.com","Creative Director | Executive Producer | Storyteller | Narrative Worlds & Creative Production Systems\r\nFounder @TheHive-Mind ","2026-11-14 21:48:38",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add TheAngryPit\u002FTheAngrySkills --skill debug-voice",{"tool":39,"command":40},"bunx","bunx skills add TheAngryPit\u002FTheAngrySkills --skill debug-voice",{"tool":42,"command":43},"pnpm","pnpm dlx skills add TheAngryPit\u002FTheAngrySkills --skill debug-voice","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fgrok-voice\u002Fskills\u002Fdebug-voice\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M782GJ4CTPNKZN0WXTASXXZ4","X MCP guide","ALWAYS read this before using any X tool (the X plugin, any X MCP, or Grok Bot's built-in public X reads) and again on any X error. X tools are included in Grok Bot at no cost: never estimate costs, check credits, or tell the user to buy credits. tools=0 \u002F user-X-* not found is a setup failure, not a paywall. Covers Spaces, communities, and Lists (reads and list writes), X Chat (XChat, inbox, DMs, unread, message requests, Chat PIN, juicebox, xchat_lite: clone xchat-grokbot-helper yourself and decrypt locally), scheduled X calls (schedule_call, list_scheduled_calls and the other call tools), and livestreams (stream sources, broadcasts, scheduled broadcasts, broadcast chat, moderators, mutes). Chat, call, livestream, Spaces, or Lists tools missing while other X tools work: reconnect the X plugin.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fx\u002Fskills\u002Fx-api-mcp-guide\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M782GBW77901ESC9PD3XAM6V","X Money guide","Read this before the first X Money action in a session and again on any X Money error, refusal, or missing capability. Covers the approval rule for every action that moves money (always ask, every time, no exceptions), how the connection works (connection code plus passkey in the X app), how to guide the user through connect, reconnect, and revoke at x.com\u002Fi\u002Fmoney\u002Fsettings\u002Fconnections, and what each failure message means.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fx-money\u002Fskills\u002Fx-money-guide\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M782G7CMYD2JSVT3RX81QRB8","google-slides","Build and edit Google Slides through the google-slides MCP tools - slides, grids of cards and columns, text boxes, shapes, images, tables, styling, layout inspection, and per-slide PNG rendering. Use when creating a deck, laying out slide elements, matching a template, or verifying how a slide looks.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fgoogle-slides\u002Fskills\u002Fgoogle-slides\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M782G4DDAJ4SMGJEF13HTX69","google-sheets","Build and edit Google Sheets with the google-sheets tools - values, formatting, charts, conditional formatting, structure, validation, named and protected ranges. Use when creating a spreadsheet or dashboard, formatting cells, adding or fixing charts, or reorganizing tabs and rows.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fgoogle-sheets\u002Fskills\u002Fgoogle-sheets\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M782G1F8QNMNKRSY6M3Y0QG6","google-drive","Work with Google Drive through its MCP tools - search, read, create, organize, share, comment, and export files. Use when creating files in specific folders, moving or renaming, converting Markdown\u002FCSV into Docs\u002FSheets, managing comments, or exporting a rendered PDF.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fgoogle-drive\u002Fskills\u002Fgoogle-drive\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M782FYVJ5XTP2R0B446RRYTX","google-docs","Author and edit Google Docs with the google-docs tools - structured writing, character and paragraph styling, lists, tables, images, headers\u002Ffooters. Use when creating a formatted document, editing document content, or applying styles.","https:\u002F\u002Fgithub.com\u002FTheAngryPit\u002FTheAngrySkills\u002Fblob\u002Fmain\u002Fsources\u002Fcursor-plugins\u002Fupstream-tree\u002Fthird_party\u002Fgoogle-docs\u002Fskills\u002Fgoogle-docs\u002FSKILL.md",[],[]]