Skill: abeltennyson/abe-audio-transcribe (version 1.0.0)

--- name: assemblyai-transcribe description: > Transcribe, diarise, translate, post-process, and structure audio/video with AssemblyAI. Use this skill when the user wants AssemblyAI specifically, needs high-quality speech-to-text from a local file or URL, wants speaker labels or named speakers, language detection, subtitles, paragraph/sentence exports, topic/entity/sentiment extraction, Speech Understanding, or agent-friendly transcript output as Markdown or normalised JSON for downstream AI workflows. compatibility: Requires Node.js 18+ with internet access and SKILLBOSS_API_KEY. metadata: author: OpenAI version: "2.0.0" homepage: https://www.assemblyai.com/docs clawdbot: skillKey: assemblyai emoji: "🎙️" requires: bins: - node env: - SKILLBOSS_API_KEY primaryEnv: SKILLBOSS_API_KEY --- # AssemblyAI transcription, Speech Understanding, and agent-friendly exports Use this skill when the user wants **AssemblyAI** rather than generic transcription, or when the job benefits from AssemblyAI-specific capabilities such as: - model routing across `universal-3-pro` and `universal-2` - language detection and code switching - diarisation plus **speaker name / role mapping** - translation, custom formatting, or AssemblyAI speaker identification - subtitles, paragraphs, sentences, topic / entity / sentiment tasks - transcript output that is easy for **other agents** to consume as Markdown or normalised JSON The skill is designed for AI agents like OpenClaw, not just end users. It provides: 1. **A no-dependency Node CLI** in `scripts/assemblyai.mjs` (and a compatibility wrapper at `assemblyai.mjs`) 2. **Bundled model/language knowledge** via `models` and `languages` commands 3. **Stable transcript output formats** - agent-friendly Markdown - normalised agent JSON - bundle manifests for downstream automation 4. **Speaker mapping workflows** - manual speaker/channel maps - AssemblyAI speaker identification - merged display names in both Markdown and JSON 5. **AssemblyAI LLM Gateway integration** for structured extraction from transcripts ## Use this skill in this order ### 1) Decide whether the user needs AssemblyAI-specific behaviour If they just want “a transcript”, a generic solution may be enough. Reach for this skill when the user mentions AssemblyAI, wants a specific AssemblyAI feature, or needs the richer outputs and post-processing this skill provides. ### 2) Pick the best entry point - **New transcription** → `transcribe` - **Existing transcript id** → `get` or `wait` - **Re-render existing saved JSON** → `format` - **Post-process an existing transcript** → `understand` - **Run transcript text through LLM Gateway** → `llm` - **Need a quick capability lookup before deciding** → `models` or `languages` ### 3) Prefer the agent-friendly defaults For most unknown-language or mixed-language jobs, prefer: ```bash node {baseDir}/assemblyai.mjs transcribe INPUT --bundle-dir ./assemblyai-out --all-exports ``` Why: - the CLI defaults to **auto-best** routing when models are not specified - it writes a **manifest + multiple files** that agents can inspect without reparsing terminal output - Markdown and agent JSON become available immediately for follow-on steps ## Quick-start recipes ### Best general default Use this when the source language is unknown or could be outside the 6-language Universal-3-Pro set: ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --bundle-dir ./out --all-exports ``` This defaults to model routing plus language detection unless the request already specifies a model or language. ### Best known-language accuracy If the language is known and supported by Universal-3-Pro, prefer an explicit request: ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --speech-model universal-3-pro --language-code en_us --bundle-dir ./out ``` ### Meeting / interview with speaker labels ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --speaker-labels --bundle-dir ./out ``` ### Add explicit speaker names or roles Manual mapping: ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --speaker-labels --speaker-map @assets/speaker-map.example.json --bundle-dir ./out ``` AssemblyAI speaker identification: ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --speaker-labels --speaker-type role --known-speakers "host,guest" --bundle-dir ./out ``` Or post-process an existing transcript: ```bash node {baseDir}/assemblyai.mjs understand TRANSCRIPT_ID --speaker-type name --speaker-profiles @assets/speaker-profiles-name.example.json --bundle-dir ./out ``` ### Translation ```bash node {baseDir}/assemblyai.mjs transcribe ./meeting.mp3 --translate-to de,fr --match-original-utterance --bundle-dir ./out ``` ### Structured extraction through LLM Gateway ```bash node {baseDir}/assemblyai.mjs llm TRANSCRIPT_ID --prompt @assets/example-prompt.txt --schema @assets/llm-json-schema.example.json --out ./summary.json ``` ## Command guidance ## `transcribe` Use for local files or remote URLs. - Local files are uploaded first. - Public URLs are sent directly to AssemblyAI. - Waits by default, then renders output. Prefer `--bundle-dir` for anything longer than a trivial clip. ## `get` / `wait` Use when you already have the transcript id. `wait` blocks until completion; `get` fetches immediately unless you add `--wait`. ## `format` Use when you already saved: - raw transcript JSON from AssemblyAI, or - the normalised agent JSON produced by this skill This is useful when you want to apply a new speaker map, re-render Markdown, or generate a fresh bundle without retranscribing. ## `understand` Use when you need AssemblyAI **Speech Understanding** on an existing transcript: - translation - speaker identification - custom formatting This command fetches the transcript, merges in the returned understanding results, then renders updated Markdown / agent JSON / bundle outputs. ## `llm` Use when the user wants: - summaries - extraction - structured JSON - downstream reasoning over the transcript Prefer `--schema` when the next step is automated. ## Output strategy ### Best default for agents: bundle mode `--bundle-dir` writes a directory containing: - Markdown transcript - agent JSON - raw JSON - optional paragraphs / sentences / subtitles - a machine-readable manifest This is usually better than dumping everything to stdout. ### Primary output kinds Use `--export` to choose the main output: - `markdown` (default) - `agent-json` - `json` / `raw-json` - `text` - `paragraphs` - `sentences` - `srt` - `vtt` - `manifest` ### Sidecar outputs You can request extra files directly with: - `--markdown-out` - `--agent-json-out` - `--raw-json-out` - `--paragraphs-out` - `--sentences-out` - `--srt-out` - `--vtt-out` - `--understanding-json-out` ## Speaker mapping rules Speaker display names are merged in this order: 1. manual `--speaker-map` 2. AssemblyAI speaker identification mapping 3. fallback generic names like `Speaker A` or `Channel 1` This means you can let AssemblyAI identify speakers first, then still override individual display names later. Example manual map file: `assets/speaker-map.example.json` ## Model and language lookup Before choosing parameters, inspect the bundled reference data: ```bash node {baseDir}/assemblyai.mjs models node {baseDir}/assemblyai.mjs models --format json node {baseDir}/assemblyai.mjs languages --model universal-3-pro node {baseDir}/assemblyai.mjs languages --model universal-2 --codes --format json ``` The bundled data lives in: - `assets/model-capabilities.json` - `assets/language-codes.json` ## Important operating notes - Keep API keys out of chat logs; use environment injection. - Use the **EU** AssemblyAI base URL when the user explicitly needs EU processing. - Uploads and transcript creation must use API keys from the **same AssemblyAI project**. - Prefer `--bundle-dir` or `--out` for long outputs. - The CLI is non-interactive and sends diagnostics to stderr, which makes it easier for agents to script reliably. - Use raw `--config` or `--request` when you need a newly added AssemblyAI parameter that this skill has not exposed yet. ## Reference files Read these when you need more depth: - [Capabilities](references/capabilities.md) - [Workflows and recipes](references/workflows.md) - [Output formats](references/output-formats.md) - [Speaker mapping](references/speaker-mapping.md) - [LLM Gateway notes](references/llm-gateway.md) - [Troubleshooting](references/troubleshooting.md) ## Key bundled files - `assemblyai.mjs` — root wrapper for compatibility with the original skill - `scripts/assemblyai.mjs` — main CLI - `assets/speaker-map.example.json` - `assets/speaker-profiles-name.example.json` - `assets/speaker-profiles-role.example.json` - `assets/custom-spelling.example.json` - `assets/llm-json-schema.example.json` - `assets/transcript-agent-json-schema.json` ## Sanity checks before finishing a task - Did you pick the right region (`api.assemblyai.com` vs `api.eu.assemblyai.com`)? - Did you choose a model strategy that matches the language situation? - If speaker naming matters, did you enable diarisation and/or provide a speaker map? - If the result will feed another agent, did you produce Markdown and/or agent JSON rather than only raw stdout? - If the transcript will be machine-consumed, did you keep the manifest or explicit output filenames?

path: assemblyai.mjs
content: #!/usr/bin/env node
import { main } from './scripts/assemblyai.mjs';

main(process.argv.slice(2)).catch((err) => {
  const message = err?.stack ?? err?.message ?? String(err);
  process.stderr.write(`${message}\n`);
  process.exit(1);
});


path: assets/custom-spelling.example.json
content: [
  {
    "from": [
      "open claw",
      "openclaw",
      "open-claw"
    ],
    "to": "OpenClaw"
  },
  {
    "from": [
      "assembly a i",
      "assembly a.i.",
      "assembly ai"
    ],
    "to": "AssemblyAI"
  }
]


path: assets/example-prompt.txt
content: Summarise the meeting for a software team.

Return:
- one concise title
- a short summary paragraph
- action items with clear owners
- any explicit decisions

Prefer speaker names if available. If the transcript is uncertain, say so briefly rather than inventing details.


path: assets/language-codes.json
content: {
  "as_of": "2026-03-14",
  "source": "AssemblyAI transcript API language_code enum as documented on 2026-03-14",
  "codes": [
    "en",
    "en_au",
    "en_uk",
    "en_us",
    "es",
    "fr",
    "de",
    "it",
    "pt",
    "nl",
    "af",
    "sq",
    "am",
    "ar",
    "hy",
    "as",
    "az",
    "ba",
    "eu",
    "be",
    "bn",
    "bs",
    "br",
    "bg",
    "my",
    "ca",
    "zh",
    "hr",
    "cs",
    "da",
    "et",
    "fo",
    "fi",
    "gl",
    "ka",
    "el",
    "gu",
    "ht",
    "ha",
    "haw",
    "he",
    "hi",
    "hu",
    "is",
    "id",
    "ja",
    "jw",
    "kn",
    "kk",
    "km",
    "ko",
    "lo",
    "la",
    "lv",
    "ln",
    "lt",
    "lb",
    "mk",
    "mg",
    "ms",
    "ml",
    "mt",
    "mi",
    "mr",
    "mn",
    "ne",
    "no",
    "nn",
    "oc",
    "pa",
    "ps",
    "fa",
    "pl",
    "ro",
    "ru",
    "sa",
    "sr",
    "sn",
    "sd",
    "si",
    "sk",
    "sl",
    "so",
    "su",
    "sw",
    "sv",
    "tl",
    "tg",
    "ta",
    "tt",
    "te",
    "th",
    "bo",
    "tr",
    "tk",
    "uk",
    "ur",
    "uz",
    "vi",
    "cy",
    "yi",
    "yo"
  ]
}


path: assets/llm-json-schema.example.json
content: {
  "name": "meeting_summary",
  "strict": true,
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "title": {
        "type": "string"
      },
      "summary": {
        "type": "string"
      },
      "action_items": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "task": {
              "type": "string"
            },
            "owner": {
              "type": "string"
            },
            "deadline": {
              "type": "string"
            }
          },
          "required": [
            "task",
            "owner",
            "deadline"
          ]
        }
      },
      "decisions": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "title",
      "summary",
      "action_items",
      "decisions"
    ]
  }
}


path: assets/model-capabilities.json
content: {
  "as_of": "2026-03-14",
  "source_notes": [
    "Bundled summary derived from AssemblyAI documentation current as of 2026-03-14.",
    "Use raw --config / --request fields if AssemblyAI adds new parameters before this skill is updated."
  ],
  "regions": {
    "stt": {
      "us": "https://api.assemblyai.com",
      "eu": "https://api.eu.assemblyai.com"
    },
    "llm_gateway": {
      "us": "https://llm-gateway.assemblyai.com",
      "eu": "https://llm-gateway.eu.assemblyai.com"
    }
  },
  "speech_models": [
    {
      "id": "universal-3-pro",
      "summary": "Highest-accuracy pre-recorded STT model in AssemblyAI docs, with advanced prompting, larger keyterm limits, and built-in code switching across its supported languages.",
      "recommended_when": [
        "You want the highest documented accuracy",
        "You need prompt guidance",
        "You need keyterms prompting at larger scale",
        "You are transcribing English, Spanish, French, German, Italian, or Portuguese"
      ],
      "supported_languages_note": "Supported across 6 language families: English, Spanish, French, German, Italian, Portuguese, including major regional variants.",
      "language_families": [
        "English: American, British, Australian",
        "Spanish: Castilian, Mexican, Argentine, Colombian, Chilean, Caribbean, Spanglish",
        "French: Metropolitan, Quebecois, Belgian",
        "German",
        "Italian: Standard",
        "Portuguese: Brazilian, European"
      ],
      "supported_language_codes_hint": [
        "en",
        "en_us",
        "en_uk",
        "en_au",
        "es",
        "fr",
        "de",
        "it",
        "pt"
      ],
      "prompting": "Documented prompt support up to 1,500 words",
      "keyterms_limit": "Up to 1,000 keyterms",
      "features": [
        "built-in code switching",
        "speaker diarisation",
        "multichannel",
        "custom spelling",
        "speech understanding",
        "topic / key phrase / entity / sentiment tasks"
      ]
    },
    {
      "id": "universal-2",
      "summary": "Wide-coverage pre-recorded STT model with 99-language support and documented automatic language detection.",
      "recommended_when": [
        "You need broadest language coverage",
        "You are routing as a fallback behind Universal-3-Pro",
        "You need AssemblyAI support for languages outside U3 Pro coverage"
      ],
      "supported_languages_note": "99-language coverage across high/good/moderate/fair accuracy bands in AssemblyAI docs.",
      "keyterms_limit": "Up to 200 keyterms",
      "features": [
        "automatic language detection",
        "code switching via language detection options",
        "speaker diarisation",
        "multichannel",
        "custom spelling",
        "topic / key phrase / entity / sentiment tasks"
      ],
      "language_accuracy_bands": {
        "high_accuracy": [
          "English",
          "Spanish",
          "French",
          "German",
          "Indonesian",
          "Italian",
          "Japanese",
          "Dutch",
          "Polish",
          "Portuguese",
          "Russian",
          "Turkish",
          "Ukrainian",
          "Catalan"
        ],
        "good_accuracy": [
          "Arabic",
          "Azerbaijani",
          "Bulgarian",
          "Bosnian",
          "Mandarin Chinese",
          "Czech",
          "Danish",
          "Greek",
          "Estonian",
          "Finnish",
          "Galician",
          "Hindi",
          "Croatian",
          "Hungarian",
          "Korean",
          "Macedonian",
          "Malay",
          "Norwegian",
          "Romanian",
          "Slovak",
          "Swedish",
          "Swiss German",
          "Tagalog",
          "Thai",
          "Urdu",
          "Vietnamese"
        ],
        "moderate_accuracy": [
          "Afrikaans",
          "Belarusian",
          "Welsh",
          "Persian / Farsi",
          "Hebrew",
          "Armenian",
          "Icelandic",
          "Kazakh",
          "Lithuanian",
          "Latvian",
          "Maori",
          "Marathi",
          "Slovenian",
          "Swahili",
          "Tamil"
        ],
        "fair_accuracy": [
          "Amharic",
          "Assamese",
          "Bengali",
          "Gujarati",
          "Hausa",
          "Javanese",
          "Georgian",
          "Khmer",
          "Kannada",
          "Luxembourgish",
          "Lingala",
          "Lao",
          "Malayalam",
          "Mongolian",
          "Maltese",
          "Burmese",
          "Nepali",
          "Occitan",
          "Punjabi",
          "Pashto",
          "Sindhi",
          "Shona",
          "Somali",
          "Serbian",
          "Telugu",
          "Tajik",
          "Uzbek",
          "Yoruba"
        ]
      }
    }
  ],
  "routing_recipes": [
    {
      "name": "Best general default",
      "request": {
        "speech_models": [
          "universal-3-pro",
          "universal-2"
        ],
        "language_detection": true
      },
      "description": "Route to Universal-3-Pro for supported languages and fall back to Universal-2 elsewhere."
    },
    {
      "name": "Known U3 language",
      "request": {
        "speech_model": "universal-3-pro",
        "language_code": "en_us"
      },
      "description": "Use a single U3 Pro request when you already know the language is covered."
    },
    {
      "name": "Meeting / interview with named speakers",
      "request": {
        "speech_models": [
          "universal-3-pro",
          "universal-2"
        ],
        "language_detection": true,
        "speaker_labels": true,
        "speech_understanding": {
          "request": {
            "speaker_identification": {
              "speaker_type": "role",
              "known_values": [
                "host",
                "guest"
              ]
            }
          }
        }
      },
      "description": "Diarise, then ask AssemblyAI to map generic speakers to names or roles."
    }
  ],
  "llm_gateway": {
    "summary": "AssemblyAI LLM Gateway provides a unified chat completions interface and structured outputs. EU LLM Gateway supports Claude and Gemini families; OpenAI models are documented on the US gateway.",
    "notes": [
      "Summarisation fields on the transcription API are deprecated; use LLM Gateway instead.",
      "The gateway only sees the text you send it, so this skill can format speaker-aware transcript text before calling it."
    ]
  }
}


path: assets/speaker-map.example.json
content: {
  "A": {
    "display": "Host",
    "source": "manual"
  },
  "B": {
    "display": "Guest",
    "source": "manual"
  },
  "channel:0": {
    "display": "Left channel / Agent",
    "source": "manual"
  },
  "channel:1": {
    "display": "Right channel / Customer",
    "source": "manual"
  }
}


path: assets/speaker-profiles-name.example.json
content: name: Tristan
description: Host of the discussion; asks the questions and guides the agenda.
company: Independent
title: Host

name: Jess
description: Guest speaker and primary respondent.
company: Independent
title: Guest

path: assets/speaker-profiles-role.example.json
content: role: agent
description: Support representative who opens and steers the call.

role: customer
description: Customer describing the problem and answering follow-up questions.

path: assets/transcript-agent-json-schema.json
content: {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "assemblyai-transcribe-agent-json-v2",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "schema_version": {
      "type": "string"
    },
    "generated_at": {
      "type": "string"
    },
    "source": {
      "type": "object"
    },
    "transcript": {
      "type": "object",
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": [
            "string",
            "null"
          ]
        },
        "audio_url": {
          "type": [
            "string",
            "null"
          ]
        },
        "text": {
          "type": "string"
        },
        "language_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "language_confidence": {
          "type": [
            "number",
            "null"
          ]
        },
        "confidence": {
          "type": [
            "number",
            "null"
          ]
        },
        "speech_model_used": {
          "type": [
            "string",
            "null"
          ]
        },
        "speech_models_requested": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "text"
      ]
    },
    "speaker_map": {
      "type": "object"
    },
    "utterances": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "index": {
            "type": "integer"
          },
          "start_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "end_ms": {
            "type": [
              "number",
              "null"
            ]
          },
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          },
          "speaker_raw": {
            "type": [
              "string",
              "null"
            ]
          },
          "speaker_display": {
            "type": "string"
          },
          "channel": {
            "type": [
              "number",
              "null"
            ]
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ]
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "index",
          "start",
          "end",
          "speaker_display",
          "text"
        ]
      }
    },
    "translated_texts": {
      "type": "object"
    },
    "speech_understanding": {
      "type": "object"
    }
  },
  "required": [
    "schema_version",
    "generated_at",
    "source",
    "transcript",
    "speaker_map",
    "utterances"
  ]
}


path: references/capabilities.md
content: # AssemblyAI capabilities reference for this skill

This file is the human-readable summary behind the `models` and `languages` commands.

## Core STT endpoints

- US base URL: `https://api.assemblyai.com`
- EU base URL: `https://api.eu.assemblyai.com`

For LLM Gateway:

- US: `https://llm-gateway.assemblyai.com`
- EU: `https://llm-gateway.eu.assemblyai.com`

## Recommended speech model strategy

### Default recommendation
Use:

```json
{
  "speech_models": ["universal-3-pro", "universal-2"],
  "language_detection": true
}
```

Reason:

- Universal-3-Pro is preferred where supported
- Universal-2 acts as the broad fallback
- this avoids silently defaulting to a single language when the source language is unknown

### When to force Universal-3-Pro
Use explicit Universal-3-Pro when:

- the language is known to be one of its supported families
- you want prompting support
- you want the larger keyterms limit

### When to lean on Universal-2
Use Universal-2 explicitly when:

- the language is outside Universal-3-Pro coverage
- you want the simplest “wide coverage” choice
- you do not need Universal-3-Pro-only prompting behaviour

## Universal-3-Pro

Supported language families and dialect notes:

- English: American, British, Australian
- Spanish: Castilian, Mexican, Argentine, Colombian, Chilean, Caribbean, Spanglish
- French: Metropolitan, Quebecois, Belgian
- German
- Italian: Standard
- Portuguese: Brazilian, European

Key capabilities called out in AssemblyAI docs:

- highest-accuracy positioning
- prompting support
- keyterms prompt up to 1,000 entries
- built-in code switching across supported languages

## Universal-2

AssemblyAI documents 99-language coverage, grouped by accuracy band.

### High accuracy
English, Spanish, French, German, Indonesian, Italian, Japanese, Dutch, Polish, Portuguese, Russian, Turkish, Ukrainian, Catalan

### Good accuracy
Arabic, Azerbaijani, Bulgarian, Bosnian, Mandarin Chinese, Czech, Danish, Greek, Estonian, Finnish, Galician, Hindi, Croatian, Hungarian, Korean, Macedonian, Malay, Norwegian, Romanian, Slovak, Swedish, Swiss German, Tagalog, Thai, Urdu, Vietnamese

### Moderate accuracy
Afrikaans, Belarusian, Welsh, Persian / Farsi, Hebrew, Armenian, Icelandic, Kazakh, Lithuanian, Latvian, Maori, Marathi, Slovenian, Swahili, Tamil

### Fair accuracy
Amharic, Assamese, Bengali, Gujarati, Hausa, Javanese, Georgian, Khmer, Kannada, Luxembourgish, Lingala, Lao, Malayalam, Mongolian, Maltese, Burmese, Nepali, Occitan, Punjabi, Pashto, Sindhi, Shona, Somali, Serbian, Telugu, Tajik, Uzbek, Yoruba

## Feature notes

### Speaker diarisation
Enable `speaker_labels=true` when you need generic speaker segments such as `A`, `B`, etc.

### Speaker identification
Use AssemblyAI Speech Understanding when you want those generic labels mapped to real names or roles.

### Custom spelling
This is a strong fit for product names, company names, uncommon surnames, technical terms, and branded spellings. Example asset: `assets/custom-spelling.example.json`

### Translation
Use Speech Understanding translation when you need transcript-level or utterance-aligned translations.

### Custom formatting
Use Speech Understanding custom formatting when dates, phone numbers, and emails need normalised presentation.

### Topics, key phrases, entities, sentiment
The CLI exposes common flags:

- `--iab-categories`
- `--auto-highlights`
- `--entity-detection`
- `--sentiment-analysis`

These sections are also surfaced in the Markdown and agent JSON outputs when present.

## Export endpoints

The skill supports:

- transcript JSON
- agent-friendly Markdown
- normalised agent JSON
- text
- paragraphs
- sentences
- subtitles (`srt`, `vtt`)

## Important deprecations

### Summarisation fields on the transcription API
The old summarisation parameters on the transcription API are deprecated. Use the LLM Gateway for summaries and structured extraction.

### LeMUR
LeMUR is deprecated in favour of the LLM Gateway. The CLI therefore includes an `llm` command rather than a LeMUR workflow.

## Bundled machine-readable references

- `assets/model-capabilities.json`
- `assets/language-codes.json`


path: references/llm-gateway.md
content: # LLM Gateway notes

Use the `llm` command when the user wants more than transcription:

- summaries
- action items
- structured JSON
- downstream reasoning
- extraction from a transcript that already exists

## Why this skill includes an `llm` command

AssemblyAI's older transcription summarisation fields are deprecated, and LeMUR is deprecated in favour of the LLM Gateway.

This skill therefore prepares transcript text and sends it to:

- `https://llm-gateway.assemblyai.com/v1/chat/completions`
- or the EU equivalent when configured

## Speaker-aware transcript formatting

The LLM Gateway only sees the text you send it.

For transcripts with speakers, this skill can convert the transcript into lines like:

```text
[00:00:00.000] Host: Welcome everyone
[00:00:04.200] Guest: Thanks for having me
```

That is the default `--input-format speaker-aware`.

Other options:

- `--input-format plain`
- `--input-format markdown`

## Structured outputs

When the next step is automated, prefer `--schema`.

Example:

```bash
node {baseDir}/assemblyai.mjs llm TRANSCRIPT_ID   --prompt @assets/example-prompt.txt   --schema @assets/llm-json-schema.example.json   --out ./summary.json
```

This is usually better than asking for free-form text and trying to parse it later.

## Raw request override

If you need a newer or more specialised LLM Gateway parameter, use:

```bash
node {baseDir}/assemblyai.mjs llm TRANSCRIPT_ID   --request @my-chat-body.json
```

The CLI then sends your request body as-is.

## Good default pattern for agents

1. generate transcript bundle
2. inspect agent JSON or Markdown
3. call `llm` with a schema if the next step is automated
4. keep the raw LLM response as a sidecar when debugging


path: references/output-formats.md
content: # Output formats

This skill deliberately exposes multiple output shapes because different follow-on tasks benefit from different formats.

## 1. Markdown transcript (`--export markdown`)

Best for:

- another LLM or agent reading the transcript
- a human reviewing the result
- preserving speaker names and timestamps in a compact way

Structure:

- `# AssemblyAI Transcript`
- `## Metadata`
- `## Speaker Map` (when relevant)
- `## Transcript`
- optional sections for chapters, key phrases, topics, entities, sentiment, translations, custom formatting, and word-level timestamps

Design goals:

- stable headings
- compact metadata
- speaker-aware transcript lines
- easy skimming
- easy chunking by downstream agents

## 2. Agent JSON (`--export agent-json`)

Best for:

- scripts and deterministic downstream processing
- tools that need stable key names
- preserving merged speaker display names without re-implementing mapping logic

Top-level shape:

- `schema_version`
- `generated_at`
- `source`
- `transcript`
- `features`
- `speaker_map`
- `utterances`
- `words` (only when requested)
- `chapters`
- `highlights`
- `topics`
- `entities`
- `sentiment`
- `translated_texts`
- `speech_understanding`

Schema asset:

- `assets/transcript-agent-json-schema.json`

## 3. Raw JSON (`--export json`)

Best for:

- debugging exact AssemblyAI responses
- validating new API fields
- preserving the original response for later re-rendering

## 4. Bundle mode (`--bundle-dir`)

Best for:

- AI-agent pipelines
- multi-step workflows
- keeping several exports together without inventing filenames later

Bundle contents typically include:

- `*.transcript.md`
- `*.agent.json`
- `*.raw.json`
- `*.manifest.json`

With `--all-exports`, the bundle also includes:

- `*.paragraphs.txt`
- `*.sentences.txt`
- `*.srt`
- `*.vtt`

The manifest is especially useful because another agent can read a single JSON file and discover the rest.

## Speaker map precedence

When rendering Markdown or agent JSON, this skill resolves speaker display names in the following order:

1. manual speaker map (`--speaker-map`)
2. AssemblyAI speaker identification mapping
3. fallback label generated from the raw speaker/channel token

That means:

- AssemblyAI can generate an initial mapping
- you can later override just one or two speakers without redoing everything

## Why bundle mode is the default recommendation

Agents often do better when:

- the main transcript is in Markdown
- the canonical machine-readable copy is separate
- filenames are explicit
- a manifest tells them where everything lives

That is why the recommended default workflow is:

```bash
node {baseDir}/assemblyai.mjs transcribe INPUT --bundle-dir ./out --all-exports
```


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)