explainer-audio-dialogue

Files (3)

• SKILL.md
• references.md
• conversational-act-patterns.md · references/

SKILL.md (first lines)

# Audio Dialogue Script

Turn one exact Guide plan into a **human-readable two-speaker dialogue script**
(台本) in the NotebookLM "audio overview" shape. Own speaker moves, spoken
orientation, register realization, and natural phrasing. Do not select coverage,
choose the cast pair, build the explanatory spine, review your own content,
produce VOICEVOX notation, or synthesize audio.

The readable script is the review/edit authority. [[explainer-audio-dialogue-review]]
accepts it before [[explainer-audio-voicevox]] creates a synthesis-specific pair.

The two speakers are **not two hosts sharing a lecture**. They differ in
*understanding*: one has not got it yet, the other explains. That asymmetry makes
the script a dialogue rather than a narration.

## When this applies

The primary input is a Guide plan produced by [[explainer-audio-guide-plan]]. If
the caller has only Markdown, create that plan first rather than selecting and
structuring content inside this skill.

When invoked as a source-workflow phase, first apply
[[explainer-content-workflow-base]], read the selected profile, and require exact
paths and digests for the run request, selected Content brief, Run Manifest,
planned Guide plan and readable-dialogue entries, profile structure/evidence,
and source report. Validate that the Guide plan digest and Manifest dependency
match before writing. Use the Guide plan as the teaching contract and the named
report as the immediate factual source. Return a structured
missing/incompatible-input result rather than recovering
choices from prior conversation or selecting the latest planning Artifact.

Continue to treat the named report as the immediate content source, and consult
the canonical structure, other reports, or narrow source loci when the script
needs book-wide context or fidelity checks. Planning Artifacts supplement those
sources; they never replace them. Set-level fan-out and human interaction belong
to the workflow coordinator, not to this single-script authoring skill.

For standalone use, require an exact `dialogue/<slug>.guide.yaml`, its source
path and digest, and an explicit output choice. Do not reconstruct a private
plan from chat history.

Before writing, read `references/conversational-act-patterns.md`. It owns the
patterns, and the rules that hold across all of them.

## Output location

Write only the exact planned `dialogue/<slug>.txt` path for workflow use. For
standalone use, write the same path beside the Guide plan and source.

`<slug>` names the source: `overview` for `reports/overview.md`, the section slug
for a deep-dive report (e.g. `chapter-2`), otherwise the source basename. Create
planned directories if missing. Honor the path action: `create` fails when the
path exists and `replace` authorizes replacing only that path. In standalone
use, do not silently overwrite the script.

## Dialogue script format

The file is plain text with one turn per speaker, prefixed with `A:` or `B:`, and
uses normal Japanese:

```
# style: natural
# Lines starting with '#' are comments and are ignored.
A: この行で話者Aの発話が始まります。
B: この行で話者Bに切り替わります。
   接頭辞のない行は、
   直前の話者の発話としてそのまま続きます。
```

- **First line: `# style: <pair>`** — the exact cast pair from the Guide plan's
  `cast_pair`. It is a comment and is not spoken. Always emit it.
- `A:` / `B:` (lowercase and full-width `：` also accepted) starts a turn.
- Lines without a prefix continue the current turn.
- `#` lines and blank lines are ignored.

## Spoken orientation

Every guide must identify itself in its first 2–4 spoken turns. The listener
must be able to determine, without seeing the filename or player UI:

- the book or document being discussed;
- whether this is an overview or a focused guide;
- the topic covered in this recording;
- what they should understand by the end.

Comments and metadata do not satisfy this requirement because they are not
spoken. Resolve the source title from an explicit document title, a title
provided by the caller, or a source heading, in that order. Do not invent a
title. If the source has no formal title, speak an accurate description that
identifies it.

Keep sample deliverable text source-neutral. Use placeholders for source-derived
proper nouns and distinctive facts that could be copied into generated output;
never transplant them from user feedback, prior artifacts, or a real source.

The shapes below are in plain 敬体 because what they fix is the four pieces of
information, not a voice. Render them in the selected pair's register;
[[explainer-audio-cast-base]] shows the same opening transposed into a character
register.

For an overview, use this shape while adapting the wording to the source:

```text
A: 今回は『{source_title}』という本の全体像を見ていきます。
B: はい。この本は、{source_summary}を扱っています。
A: 聞き終える頃には、{listener_destination}を説明できるようになるわけですね。
B: そのために、まず{opening_topic}から考えます。
```

For a focused guide, use this shape while adapting the wording to the source:

```text
A: 今回は『{source_title}』の中から、{focused_topic}を掘り下げます。
B: はい。聞き終える頃には、{listener_destination}が分かります。
A: では、{opening_question}？
B: そこから考えていきます。
```

The brace-delimited fields are placeholders and must not appear in the finished

From choplin/explainer-studio, MIT.

More from choplin/explainer-studio