explain-for-audio

A skill for turning technical source content into a listening-friendly transcript.

The skill is focused on transcript transformation only:

• It helps rewrite text for audio delivery.
• It teaches meaning-first paraphrasing for technical content.
• It is not an audio generation pipeline.

The skill file lives at skills/explain-for-audio/SKILL.md.

Examples

The examples below show the kind of transformation this skill is designed to support.

Important narration rules reflected in the examples:

• For function definitions and function calls, say the parameter structure out loud in plain language (for example, the function takes 2 arguments, the first argument is..., it also passes a timeout named argument).
• Never speak raw code identifiers in transcript output. Convert them into plain spoken words (for example, ThreadPoolExecutor -> thread pool executor, subprocess.run -> subprocess run function, max_workers -> max workers).
• For KEY=VALUE patterns, describe both the key and the value (for example, set node underscore env to production for this command, and mention that node underscore env is a common environment key).

Example 1: Release Notes + Commands + Paths + URL

Source excerpt (reader-friendly, not audio-friendly):

# Release Notes (v1.8.0)

- Update `src/app.ts` to initialize the player earlier.
- Run `npm run build` after changing config.
- If the build fails, check `config/.env.example`.
- See https://docs.astral.sh/uv/guides/tools/ for `uvx` command patterns.

## Performance

- Default worker count increased from 4 to 8.
- Timeout remains 180 seconds.

Audio-friendly transcript (listening-first):

Here is a quick release notes summary for version 1 point 8 point 0.

First, update the app TypeScript file in the source directory so the player initializes earlier.

After you change the configuration, run the project's build step.

If the build fails, check the example environment configuration file in the config folder.

If you need the uvx command format, open the tool guide page on uv's official documentation.

Now the performance changes.

The default worker count increased from 4 to 8.

The timeout stays the same at 180 seconds.

So the main performance takeaway is: the job can run with more parallel work, but the timeout limit did not change.

Example 2: Code Review Summary (Code Snippet to Spoken Meaning)

Source excerpt:

def run_checked(cmd, timeout_seconds):
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        timeout=timeout_seconds,
        check=False,
    )
    if result.returncode != 0:
        raise RuntimeError(f"Command failed: {result.returncode}")
    return result.stdout

with ThreadPoolExecutor(max_workers=min(4, os.cpu_count() or 4)) as pool:
    ...

Audio-friendly transcript:

This function runs a command, captures the output, and waits up to the configured timeout.

It takes 2 arguments: the command to run, and the timeout in seconds.

It captures the command output as text, so later code can read it directly.

It also disables automatic exception raising for command failures at the subprocess layer.

In other words, the function keeps control over error handling so it can raise its own clearer error message.

If the command returns a non-zero exit code, it raises a runtime error and includes the return code.

Next, the code creates a thread pool executor for parallel work.

The worker count is capped at 4, and it also checks the machine CPU count with a fallback of 4.

So the concurrency behavior is controlled and predictable, instead of scaling without a limit.

Example 3: Complex Shell Command + Flags + JSON + API Meaning

Source excerpt:

curl -X POST https://api.example.com/v1/jobs \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  --data '{"task":"transcribe","priority":"high","options":{"language":"en","timestamps":true}}'

Audio-friendly transcript:

This command sends an authenticated API request to create a job.

It sends a POST request to the version 1 jobs endpoint.

The headers handle authentication and tell the server the request body is JSON.

The request body asks the service to start a transcription task.

It marks the job as high priority.

It also asks for English output with timestamps enabled.

In plain terms, this command submits an urgent transcription job and requests time-aligned results.

Example 4: Error + Status Code + Next-Step Context

Source excerpt:

HTTP 429 Too Many Requests
ModuleNotFoundError: No module named 'yaml'
ffmpeg concat failed: Invalid data found when processing input

Audio-friendly transcript:

The server returned code 429, which usually means too many requests in a short time.

In other words, the service is rate limiting requests right now.

There is also a module-not-found error, and Python could not find the yaml module.

That usually means a missing dependency in the current environment, not a logic bug in the script itself.

The ffmpeg merge step also failed because it found invalid input data while processing the audio chunks.

So there may be a problem with one of the generated chunk files, or with the concat input list.

Example 5: KEY=VALUE Should Describe Both Key and Value

Source excerpt:

NODE_ENV=production python3 app.py --mode batch

Audio-friendly transcript:

Run the Python app in batch mode.

Before the command starts, set the environment variable named node underscore env to the value production for this run.

Node underscore env is a commonly used key for selecting environment-specific app behavior, like development or production mode.

In plain terms, this runs the app with production environment behavior enabled.