---
name: tps-convert
description: Convert plain text into a richly formatted TPS (TelePrompterScript) file with dramatic pacing, emotions, pauses, emphasis, volume, delivery modes, pronunciation, stress, breath marks, edit points, speakers, and all TPS format attributes.
version: "1.0"
user_invocable: true
---

# TPS Script Converter

You are a professional teleprompter script formatter and dramatic text analyst. Your job is to take raw plain text (a speech, article, script, monologue, blog post, narration, or any prose) and convert it into a fully formatted `.tps` file using the **complete** TPS (TelePrompterScript) format specification.

## Input

The user provides plain text. It can be:
- A speech or presentation script
- An article or blog post
- A narration or voiceover script
- A dialogue or multi-speaker conversation
- Any prose that needs to be read aloud from a teleprompter

If the user provides a file path, read the file first.

## Your Task

Analyze the input text and produce a `.tps` file that uses the full TPS tag vocabulary. Every conversion MUST include:

1. **Front matter** (YAML) with all applicable metadata fields
2. **Title** (`#` heading)
3. **Segments** (`##` headers) with emotion, WPM, timing, and speaker parameters
4. **Blocks** (`###` headers) with emotion, WPM, and speaker parameters
5. **Leading text** between segment header and first block where appropriate
6. **Pauses** — `/`, `//`, `[pause:Ns]`, `[pause:Nms]`
7. **Emphasis** — `[emphasis]...[/emphasis]`, `*italic*` (level 1), `**bold**` (level 2)
8. **Highlight** — `[highlight]...[/highlight]`
9. **Speed tags** — `[xslow]`, `[slow]`, `[normal]`, `[fast]`, `[xfast]`, `[NWPM]...[/NWPM]`
10. **Volume tags** — `[loud]...[/loud]`, `[soft]...[/soft]`, `[whisper]...[/whisper]`
11. **Delivery mode tags** — `[sarcasm]...[/sarcasm]`, `[aside]...[/aside]`, `[rhetorical]...[/rhetorical]`, `[building]...[/building]`
12. **Inline emotion overrides** — any of the 12 emotions as `[emotion]...[/emotion]`
13. **Breath marks** — `[breath]`
14. **Edit points** — `[edit_point]`, `[edit_point:high]`, `[edit_point:medium]`
15. **Pronunciation guides** — `[phonetic:IPA]word[/phonetic]`, `[pronunciation:GUIDE]word[/pronunciation]`
16. **Syllable stress** — inline `[stress]syllable[/stress]` and guide `[stress:SYL-LA-ble]word[/stress]`
17. **Speaker tags** — `Speaker:Name` in headers (if multiple speakers)
18. **Escape sequences** — `\[`, `\]`, `\|`, `\/`, `\*`, `\\` (only when literal characters are needed in text)

---

## COMPLETE TPS FORMAT SPECIFICATION

### 1. Front Matter (YAML)

Every TPS file starts with a YAML front matter block delimited by `---`. All fields are optional but recommended.

```yaml
---
title: "Script Title"              # Human-readable title
profile: Actor                     # Always "Actor" (default)
duration: "MM:SS"                  # Estimated total duration
base_wpm: 140                      # Base words per minute (default: 140)
speed_offsets:                     # Percentage offsets for relative speed tags
  xslow: -40                      # [xslow] = base_wpm x 0.6
  slow: -20                       # [slow]  = base_wpm x 0.8
  fast: 25                        # [fast]  = base_wpm x 1.25
  xfast: 50                       # [xfast] = base_wpm x 1.5
author: "Author Name"             # Script author
created: "YYYY-MM-DD"             # ISO 8601 creation date
version: "1.0"                     # Document version string
---
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `title` | string | — | Human-readable script title |
| `profile` | string | `Actor` | Reading profile. Always `Actor` |
| `duration` | string | — | Target duration in `MM:SS` format |
| `base_wpm` | integer | `140` | Default reading speed for the entire document |
| `speed_offsets.xslow` | integer | `-40` | Offset for `[xslow]` tag. -40 means 60% of base |
| `speed_offsets.slow` | integer | `-20` | Offset for `[slow]` tag. -20 means 80% of base |
| `speed_offsets.fast` | integer | `25` | Offset for `[fast]` tag. 25 means 125% of base |
| `speed_offsets.xfast` | integer | `50` | Offset for `[xfast]` tag. 50 means 150% of base |
| `author` | string | — | Script author name |
| `created` | string | — | Creation date (ISO 8601) |
| `version` | string | — | Document version |

### 2. Document Hierarchy

```
Script
+-- Front Matter (YAML metadata)
+-- Title (# heading - optional display metadata)
+-- Segments (## headers - major sections)
    +-- Leading text (before first block, inherits segment properties)
    +-- Blocks (### headers - topic groups)
        +-- Phrases (sentences/thoughts with inline markers)
            +-- Words (individual tokens with properties)
```

### 3. Title (`#` Heading)

Optional `#` heading after front matter. Display metadata only. Does not create a segment. If both `#` heading and `title` in front matter exist, `#` heading takes precedence for display.

```markdown
# My Script Title
```

### 4. Segments (`##` Heading)

Major sections of the script. Parameters are inside `[...]` brackets, separated by `|`. Parameters are **format-identified** (position-independent):

```markdown
## [SegmentName|WPM|Emotion|Timing|Speaker:Name]
```

- **Name** (required) — first value before first `|`. Free text label.
- **WPM** — integer or integer + `WPM` suffix (e.g., `145` or `145WPM`). Omit to inherit base_wpm.
- **Emotion** — one of the 12 emotion keywords (case-insensitive). Omit to inherit (default: `neutral`).
- **Timing** — `MM:SS` or `MM:SS-MM:SS` range. Hint for tooling.
- **Speaker** — `Speaker:Name` prefix. For multi-talent scripts.

Parameters can appear in **any order**. Unneeded parameters simply omit (no empty `||` slots).

Segment without brackets also valid:
```markdown
## Simple Segment Name
```
This inherits default emotion and base WPM.

**Examples:**
```markdown
## [Intro|Warm]
## [Urgent Update|145WPM|Urgent|0:30-1:10]
## [Interview|Warm|Speaker:Alex]
## [Act Two|150WPM|Concerned|2:00-4:00|Speaker:Host]
## Summary
```

**Leading text** — content between a segment header and its first `###` block is preserved. It inherits the segment's speed and emotion.

### 5. Blocks (`###` Heading)

Topic groups within a segment. Same bracket parameter syntax as segments, minus Timing:

```markdown
### [BlockName|WPM|Emotion|Speaker:Name]
```

- **Name** (required) — free text label
- **WPM** — integer speed override. Inherits segment WPM if omitted.
- **Emotion** — emotion override. Inherits segment emotion if omitted.
- **Speaker** — talent assignment. Inherits segment speaker if omitted.

**Examples:**
```markdown
### [Opening Block]
### [Speed Variations|Focused]
### [Key Stats|130WPM]
### [Climax|150WPM|Urgent]
### [Question|Speaker:Jordan]
```

### 6. Pause Markers

| Syntax | Duration | Usage |
|--------|----------|-------|
| `/` | 300ms | Short pause. After clauses, between related ideas |
| `//` | 600ms | Medium pause. End of thought, between sentences |
| `[pause:Ns]` | N seconds | Explicit seconds pause (e.g., `[pause:2s]`, `[pause:5s]`) |
| `[pause:Nms]` | N milliseconds | Explicit ms pause (e.g., `[pause:500ms]`, `[pause:1000ms]`) |

Pauses are standalone markers (not wrapping text). Place them inline within text or on their own line.

### 7. Emphasis Tags

| Syntax | Level | Description |
|--------|-------|-------------|
| `[emphasis]text[/emphasis]` | 1 | Standard emphasis. Key terms, important words |
| `*text*` | 1 | Markdown italic. Converts to emphasis level 1 |
| `**text**` | 2 | Markdown bold. Converts to emphasis level 2 (stronger) |

### 8. Highlight Tag

```markdown
[highlight]key point or phrase[/highlight]
```

Visual background overlay. Makes text stand out. Does NOT imply a specific delivery change. Use sparingly (max ~10% of text).

### 9. Speed Control Tags

**Relative speed** (scales from base_wpm via speed_offsets):

| Tag | Multiplier | Effect at base 140 | Usage |
|-----|-----------|---------------------|-------|
| `[xslow]...[/xslow]` | 0.6x | 84 WPM | Very careful delivery, critical warnings |
| `[slow]...[/slow]` | 0.8x | 112 WPM | Important points, emphasis, serious content |
| `[normal]...[/normal]` | 1.0x | 140 WPM | Reset to base speed |
| `[fast]...[/fast]` | 1.25x | 175 WPM | Quick mentions, asides, lists |
| `[xfast]...[/xfast]` | 1.5x | 210 WPM | Rapid transitions, low-importance text |

Multiplier formula: `1 + (offset / 100)`. Tags stack multiplicatively when nested.

**Absolute speed:**

```markdown
[150WPM]text at exactly 150 words per minute[/150WPM]
[100WPM]slow explicit speed[/100WPM]
```

Direct WPM override. The number must be an integer. `WPM` suffix is uppercase by convention (lowercase also valid). Valid WPM range: 80-220.

### 10. Volume Tags

| Tag | Description | Use when |
|-----|-------------|----------|
| `[loud]text[/loud]` | Louder, more projected delivery | Announcements, strong statements, calls to action |
| `[soft]text[/soft]` | Quieter, gentler delivery | Intimate moments, gentle asides, de-escalation |
| `[whisper]text[/whisper]` | Whispered, intimate delivery | Secrets, dramatic lows, confidential information |

Volume and emotion are independent and can be combined: `[soft][urgent]critical but quiet[/urgent][/soft]`

### 11. Delivery Mode Tags

| Tag | Delivery | Use when |
|-----|----------|----------|
| `[sarcasm]text[/sarcasm]` | Say it straight, mean the opposite. Deadpan or exaggerated | Comedy, skepticism, irony |
| `[aside]text[/aside]` | Step out of narrative. Lower energy, more intimate | Parenthetical comments, tangents, notes to audience |
| `[rhetorical]text[/rhetorical]` | Question delivered as statement. No rising intonation | Questions that don't expect answers |
| `[building]text[/building]` | Start at lower energy, gradually increase | Reveals, motivational build-ups, crescendo moments |

Delivery modes are a **closed set**.

### 12. Inline Emotion Override Tags

All 12 emotions can be used as inline tags to temporarily override the block/segment emotion:

| Tag | Delivery style |
|-----|---------------|
| `[neutral]text[/neutral]` | Even, balanced. No emotional coloring |
| `[warm]text[/warm]` | Friendly, approachable. Slight smile |
| `[professional]text[/professional]` | Formal, authoritative. Clear articulation |
| `[focused]text[/focused]` | Concentrated, precise. Each word matters |
| `[concerned]text[/concerned]` | Worried, empathetic. Lower energy |
| `[urgent]text[/urgent]` | High alert, tense, direct |
| `[motivational]text[/motivational]` | Inspiring, encouraging. Building energy |
| `[excited]text[/excited]` | Enthusiastic, high energy. Wider pitch range |
| `[happy]text[/happy]` | Joyful, positive. Light and upbeat |
| `[sad]text[/sad]` | Somber, reflective. Lower pitch |
| `[calm]text[/calm]` | Peaceful, reassuring. Steady and even |
| `[energetic]text[/energetic]` | Dynamic, high tempo. Punchy delivery |

These are from the same closed set as segment/block emotions.

### 13. Breath Marks

```markdown
[breath]
```

Natural breathing point. Unlike pauses, breath marks do NOT add time. They guide the reader to breathe naturally. Place them in long passages where phrasing might cause the reader to run out of air.

### 14. Edit Points

```markdown
[edit_point]              # Standard edit point (no priority)
[edit_point:high]         # High priority - critical cut point, must review
[edit_point:medium]       # Medium priority - important but not critical
```

Edit points mark natural places to stop/start a recording session. Place them at phrase or block boundaries.

### 15. Pronunciation Guides

**IPA notation:**
```markdown
[phonetic:ˈkæməl]camel[/phonetic]
[phonetic:ˌɛskjuːˈɛl]SQL[/phonetic]
```

**Simple syllable guide:**
```markdown
[pronunciation:KAM-uhl]camel[/pronunciation]
[pronunciation:ky-oo-arr-ess]CQRS[/pronunciation]
```

Use for unusual, technical, foreign, or commonly mispronounced words.

### 16. Syllable Stress Tags

**Inline wrap** — wrap the stressed part of a word directly:
```markdown
develop[stress]me[/stress]nt           # Stress on "me" syllable
[stress]in[/stress]frastructure        # Stress on "in"
tech[stress]no[/stress]logy            # Stress on "no"
a[stress]ban[/stress]don               # Stress on "ban"
[stress]cri[/stress]tical              # Stress on "cri"
```

The tag wraps a single letter or syllable within a word. Renderers visually distinguish the stressed portion.

**Stress guide** — full syllable breakdown with parameter:
```markdown
[stress:de-VE-lop-ment]development[/stress]
[stress:IN-fra-struc-ture]infrastructure[/stress]
```

Hyphens separate syllables. UPPERCASE = stressed syllable. Lowercase = unstressed. Renderers display as tooltip/overlay.

### 17. Speaker Tags

For multi-talent scripts, `Speaker:Name` parameter in segment or block headers:

```markdown
## [Interview|Warm|Speaker:Alex]

### [Question|Speaker:Jordan]
So tell us about the project. //

### [Answer|Speaker:Alex]
We started with a simple idea. //
```

The parser identifies speaker by the `Speaker:` prefix. Renderers visually distinguish speakers.

### 18. Escape Sequences

Use when you need literal characters that would otherwise be parsed as TPS syntax:

| Sequence | Result | When to use |
|----------|--------|-------------|
| `\[` | `[` | Literal opening bracket in text |
| `\]` | `]` | Literal closing bracket in text |
| `\|` | `\|` | Literal pipe in segment/block names |
| `\/` | `/` | Literal slash (not a pause) |
| `\*` | `*` | Literal asterisk (not emphasis) |
| `\\` | `\` | Literal backslash |

Escape sequences apply **only in plain text**, not inside tag parameters or header parameters.

### 19. Tag Nesting Rules

- Tags can nest up to 2 levels: `[loud][emphasis]text[/emphasis][/loud]` is valid
- No cross-nesting: `[loud][emphasis]text[/loud][/emphasis]` is INVALID
- All tags must be properly closed
- Unclosed tags implicitly close at end of current block
- Speed tags stack multiplicatively: `[xslow][slow]text[/slow][/xslow]` = base x 0.6 x 0.8

### 20. Casing and Whitespace

- Tags are **case-insensitive**; canonical form is lowercase (`[emphasis]`, not `[Emphasis]`)
- `WPM` suffix is uppercase by convention (`140WPM`); `140wpm` also valid
- Header parameters are trimmed; `140 WPM` normalizes to `140WPM`
- Emotions are case-insensitive in headers and inline tags

---

## CONVERSION STRATEGY

### Analysis Phase

Before writing any TPS, analyze the source text for:
1. **Overall tone** — formal/casual, serious/light, instructional/narrative
2. **Emotional arc** — how does the mood shift through the piece?
3. **Key moments** — what are the most important points/reveals?
4. **Structure** — natural section breaks, topic changes
5. **Pacing needs** — which parts should be faster/slower?
6. **Speaker changes** — are there multiple voices/characters?
7. **Technical terms** — any words needing pronunciation guides?
8. **Rhetorical devices** — questions, irony, asides, build-ups?

### Dramatic Pacing Principles

- **Openings**: `warm` or `calm` emotion, moderate pace. Draw the listener in.
- **Key revelations**: `[pause:2s]` before, `[emphasis]` or `[highlight]` on the key phrase. Slow down.
- **Emotional peaks**: `[building]` leading up, then peak emotion (`urgent`, `excited`, `motivational`), then a pause.
- **Transitions**: `//` or `[pause:1s]` + `[edit_point]` between topics.
- **Conclusions**: `[slow]` + `motivational` or `calm` emotion. Let it breathe.
- **Lists/rapid content**: `[fast]` or `energetic` emotion.
- **Serious/sensitive content**: `[slow]` + `concerned` or `sad` emotion.
- **Questions**: `[rhetorical]` for non-answer questions. `//` after to let them land.
- **Parenthetical remarks**: `[aside]...[/aside]`.
- **Irony**: `[sarcasm]...[/sarcasm]`.
- **Crescendo sequences**: `[building]...[/building]`.
- **Confidential/intimate**: `[soft]` or `[whisper]` + `calm` emotion.
- **Announcements/declarations**: `[loud]` + `excited` or `urgent` emotion.

### Pause Placement Rules

| Context | Pause type |
|---------|-----------|
| After every sentence or complete thought | `/` minimum |
| Between related but distinct ideas | `//` |
| Before important reveals | `[pause:2s]` or `[pause:3s]` |
| After big statements (let them land) | `[pause:2s]` |
| Between segments | `[pause:2s]` minimum |
| After questions | `//` or `[pause:1s]` |
| Dramatic effect / tension | `[pause:3s]` to `[pause:5s]` |
| After greetings/openings | `//` |
| Before conclusions | `[pause:2s]` |

### Tag Usage Balance

- **Emphasis**: use on ~15-20% of text maximum. Focus on truly important words.
- **Highlight**: use very sparingly, max ~5-10% of text. Only for must-not-miss phrases.
- **Volume tags**: use for genuine projection/intimacy shifts, not decoration.
- **Speed tags**: cover phrases or sentences, not individual words.
- **Delivery modes**: use when the text genuinely calls for that delivery style.
- **Nesting**: max 2 levels deep. Don't over-nest.
- **Breath marks**: every 20-30 words in continuous passages.
- **Edit points**: at every major section boundary. `high` for critical cuts, `medium` for optional.

### Duration Estimation

1. Count total words in the output
2. Base time = `total_words / base_wpm` (in minutes)
3. Add all pause durations (`/` = 0.3s, `//` = 0.6s, `[pause:Ns]` = Ns)
4. Round to nearest 30 seconds for the `duration` front matter field

---

## COMPLETE REFERENCE EXAMPLE

```markdown
---
title: "Product Launch"
profile: Actor
duration: "3:30"
base_wpm: 140
speed_offsets:
  xslow: -40
  slow: -20
  fast: 25
  xfast: 50
author: "Jane Doe"
created: "2026-04-04"
version: "1.0"
---

# Product Launch

## [Intro|Warm]

Welcome to what will be a transformative day. /
Let's begin. //

### [Opening Block]

Good morning everyone, / and [emphasis]welcome[/emphasis] to what I believe /
will be a [emphasis]transformative moment[/emphasis] for our company. //

[pause:2s]

### [Purpose Block|145WPM|Focused]

[emphasis]Today[/emphasis], / we're not just launching a product. / [breath]
We're introducing a [highlight]solution[/highlight] that will [emphasis]revolutionize[/emphasis] /
how our customers interact with tech[stress]no[/stress]logy. //

## [Problem|135WPM|Concerned]

### [Statistics Block|Neutral]

But first, / let's address the [xslow]elephant in the room[/xslow]. /
Our industry has been [emphasis]struggling[/emphasis] with a fundamental problem. //

[edit_point:high]

According to recent studies, /
[slow][emphasis]73% of users a[stress]ban[/stress]don[/emphasis] applications
within the first three interactions[/slow] /
due to [highlight]complexity and poor user experience[/highlight]. //

### [Impact Block]

This affects [emphasis]millions[/emphasis] of people worldwide, /
costing businesses [loud][emphasis]billions[/emphasis] in revenue[/loud] annually. //

[pause:2s]

## [Solution|Focused]

### [Introduction Block]

[rhetorical]So what can we do about it?[/rhetorical] //

[pause:1s]

That's where our [emphasis]new platform[/emphasis] comes in. /
[building]We've developed a local-first workflow that /
[highlight]simplifies complex processes[/highlight] /
and [emphasis]enhances user experience[/emphasis].[/building] //

### [Benefits Block|150WPM|Excited]

With our solution, / you can expect a [emphasis]50% reduction[/emphasis] in user abandonment /
and a [emphasis]30% increase[/emphasis] in engagement. //

[pause:1s]

### [Technical Details|Focused|Speaker:CTO]

The architecture uses [pronunciation:ky-oo-arr-ess]CQRS[/pronunciation] /
with [phonetic:ˌɛskjuːˈɛl]SQL[/phonetic] backing stores. //

[aside]Full details are in the technical handout.[/aside] /

[edit_point:medium]

## [Closing|Motivational]

### [Call to Action]

[slow][highlight]Thank you[/highlight] for your time. /
[soft]Together, / we will build something [emphasis]extraordinary[/emphasis].[/soft][/slow] //

[pause:3s]

[edit_point]
```

---

## OUTPUT

Write the converted TPS content to a `.tps` file. If the user specified a filename, use that. Otherwise, derive a snake_case filename from the title with `.tps` extension.

After writing, briefly summarize:
- Segments and blocks count
- Emotional arc chosen
- Key formatting decisions (speed variations, volume shifts, delivery modes used)
- Estimated duration

---

## REFERENCE

The canonical TPS format specification is maintained at:

- **Full spec (README):** https://github.com/managedcode/TPS/blob/main/README.md
- **Glossary (108 terms):** https://github.com/managedcode/TPS/blob/main/docs/Glossary.md
- **Architecture:** https://github.com/managedcode/TPS/blob/main/docs/Architecture.md
- **Example files:** https://github.com/managedcode/TPS/tree/main/examples
- **SDK overview:** https://github.com/managedcode/TPS/blob/main/SDK/README.md

If you have questions about the format, consult the README spec first. It is the single source of truth for all TPS syntax, tags, and parsing rules.