What You’ll Learn in This Module

Cast narrations are both visual and spoken — an audio narrator reads the text aloud. But text-to-speech engines struggle with acronyms, product names, version numbers, and long digit strings. The cast_pronounce filter gives you control over how specific words are spoken, without changing how they appear on screen.

đź“– https://school.cast.app/liquid/custom-cast-filters.html#cast_pronounce

What Is cast_pronounce?

The cast_pronounce filter separates what the viewer reads from what the narrator says. You define pronunciation rules in Cast’s Pronunciations dictionary, and the filter applies them at render time. The text on screen stays exactly as written; only the audio changes.

Analogy: Think of a news anchor reading from a teleprompter. The teleprompter says “NATO” but the anchor knows to say “nay-toe.” Or the script says “Dr.” and the anchor says “Doctor.” cast_pronounce is like giving Cast’s narrator a pronunciation guide — it sees one thing on screen but says another.

Why it matters in Cast

Every industry has its own jargon. A text-to-speech engine might say “C-S-M” as “cuhsm” or “Q-B-R” as “quber.” Product version numbers like “2.1.5” might be read as “two point one point five” or as “two hundred fifteen.” Without pronunciation control, these misreadings undermine the professionalism of your Cast presentations.

Setup First — The Pronunciations Dictionary

Before using cast_pronounce, you need to add entries to your project’s Pronunciations dictionary:

Projects → Project Workflow → Pronunciations

Each entry maps a written word to its spoken form:

Written Spoken
CSM Customer Success Manager
QBR Quarterly Business Review
NPS Net Promoter Score
ARR Annual Recurring Revenue
SaaS sass
Acme ak-mee

đź“– Full pronunciation setup guide: https://school.cast.app/personalizing-content/pronunciations.html

💡 Set up your dictionary first. The cast_pronounce filter looks up words in this dictionary. If a word isn’t in the dictionary, the filter has nothing to work with.

Basic Usage — Single Word Lookup

The simplest use of cast_pronounce is looking up a single word:


Contact your {{ "CSM" | cast_pronounce }}.
Your {{ "NPS" | cast_pronounce }} score has improved.

With the dictionary entry CSM → "Customer Success Manager":

  • Screen shows: Contact your CSM.
  • Narrator says: Contact your Customer Success Manager.

The viewer sees the concise acronym; the listener hears the full phrase. Both get the ideal experience.

Real Cast example 


Your {{ "QBR" | cast_pronounce }} is scheduled for {{ qbr_date | date: "%B %d, %Y" }}.
We'll review your {{ "ARR" | cast_pronounce }} growth and {{ "NPS" | cast_pronounce }} trends.

Screen shows: Your QBR is scheduled for May 10, 2026. We'll review your ARR growth and NPS trends.

Narrator says: Your Quarterly Business Review is scheduled for May 10, 2026. We'll review your Annual Recurring Revenue growth and Net Promoter Score trends.

Pattern: number_pair — Speaking Long Numbers in Pairs

Long digit strings like phone extensions, account numbers, or metric values sound awkward when read as a single large number. The number_pair pattern breaks digits into spoken pairs:


{{ "346780" | cast_pronounce: "number_pair" }}
  • Screen shows: 346780
  • Narrator says: 34 67 80

More examples:

Input Narrator Says How It Works
"346780" 34 67 80 Split into pairs from left
"380" 3 80 Odd count: single digit first
"987654" 98 76 54 Three pairs
"12" 12 Already a pair

Real Cast example 


Your account number is {{ account_number | cast_pronounce: "number_pair" }}.

Screen shows: Your account number is 584923. Narrator says: Your account number is 58 49 23.

Pattern: by_char — Spelling Out Letter by Letter

The by_char pattern tells the narrator to read each character individually, with pauses between them. Useful for codes, identifiers, and mixed alphanumeric strings:


{{ "CSM123" | cast_pronounce: "by_char" }}
  • Screen shows: CSM123
  • Narrator says: C S M 1 2 3

More examples:

Input Narrator Says
"CSM123" C S M 1 2 3
"ROI 2024" R O I 2 0 2 4
"AB5" A B 5

Real Cast example 


Your reference code is {{ ref_code | cast_pronounce: "by_char" }}.

Screen shows: Your reference code is TKT4821. Narrator says: Your reference code is T K T 4 8 2 1.

Pattern: version — Reading Version Numbers

The version pattern reads dots as “point,” which is the natural way to speak software version numbers:


{{ "1.2.3" | cast_pronounce: "version" }}
  • Screen shows: 1.2.3
  • Narrator says: 1 point 2 point 3

More examples:

Input Narrator Says
"1.2.3" 1 point 2 point 3
"2.1.5" 2 point 1 point 5
"10.0" 10 point 0

Real Cast example 


You're currently running version {{ product_version | cast_pronounce: "version" }}.

Screen shows: You're currently running version 3.2.1. Narrator says: You're currently running version 3 point 2 point 1.

Pattern: all — Scan an Entire Sentence

The all pattern scans an entire string and applies all dictionary entries found within it. Instead of wrapping each word individually with cast_pronounce, you can process a whole sentence at once:


{{ text | cast_pronounce: "all" }}

Matching modes

The all pattern supports two matching modes:

  • "strict" (default) — matches whole words only. “CSM” in the dictionary matches the standalone word “CSM” but not “CSMs” or “CSManager.”
  • "loose" or "partial" — matches inside longer words too. “CSM” would also match within “CSMs.”

{{ text | cast_pronounce: "all" }}                 {%- # strict matching (default) -%}
{{ text | cast_pronounce: "all", "strict" }}        {%- # explicitly strict -%}
{{ text | cast_pronounce: "all", "loose" }}         {%- # partial matching -%}
{{ text | cast_pronounce: "all", "partial" }}       {%- # same as loose -%}

Real Cast example 


{%- assign message = "Your CSM will review the QBR with stakeholders to discuss ROI" -%}
{{ message | cast_pronounce: "all" }}

With CSM, QBR, and ROI all in the Pronunciations dictionary:

  • Screen shows: Your CSM will review the QBR with stakeholders to discuss ROI
  • Narrator says: Your Customer Success Manager will review the Quarterly Business Review with stakeholders to discuss Return on Investment

When to use all vs. individual lookups

Approach Best For
Individual {{ "CSM" \| cast_pronounce }} Short sentences with 1–2 terms
{{ text \| cast_pronounce: "all" }} Long paragraphs with many terms

đź’ˇ The all pattern is especially useful for narration blocks that are mostly plain text with scattered acronyms. Instead of breaking the text apart to wrap each acronym, pass the whole block through once.

Choosing the Right Pattern

Pattern Use When Example Input Narrator Says
(none — basic lookup) Single dictionary word "CSM" Customer Success Manager
"number_pair" Long digit strings "346780" 34 67 80
"by_char" Codes, identifiers "CSM123" C S M 1 2 3
"version" Software versions "1.2.3" 1 point 2 point 3
"all" Entire sentences Full paragraph All dictionary terms replaced

Common Mistakes

❌ Using cast_pronounce without adding the word to the Pronunciations dictionary:


{{ "QBR" | cast_pronounce }}

If “QBR” isn’t in the dictionary, the filter has nothing to substitute — the narrator will just read “QBR” as-is (likely as “cue-bee-arr” or similar).

✅ Always add entries to Pronunciations first: Go to Projects → Project Workflow → Pronunciations and add QBR → Quarterly Business Review, then use the filter.

❌ Wrapping entire sentences in basic (non-all) cast_pronounce:


{{ "Your CSM will review the QBR" | cast_pronounce }}

Without a pattern, the filter tries to look up the entire sentence as one dictionary entry — which won’t exist.

âś… Use the "all" pattern for sentences:


{{ "Your CSM will review the QBR" | cast_pronounce: "all" }}

❌ Forgetting that cast_pronounce only affects audio, not screen text: If you also want to change the displayed text, you need a different approach:


Contact your Customer Success Manager ({{ "CSM" | cast_pronounce }}).

This shows “Customer Success Manager (CSM)” on screen and says “Customer Success Manager Customer Success Manager” — a double reading.

âś… Let screen text and audio work independently:


Contact your {{ "CSM" | cast_pronounce }}.

Screen: Contact your CSM. | Audio: Contact your Customer Success Manager.

Try It Yourself

Exercise: You have a narration paragraph:


Your CSM has prepared your QBR materials. We'll review your NPS trends
and discuss version 4.2.1 of the platform. Your account ID is 738291.

Write the Liquid to ensure:

  1. CSM, QBR, and NPS are all spoken as their full phrases
  2. The version number is read as “4 point 2 point 1”
  3. The account ID is read as “73 82 91”

Assume CSM, QBR, and NPS are already in the Pronunciations dictionary.

Click to reveal the answer ```liquid {%- capture narration -%} Your CSM has prepared your QBR materials. We'll review your NPS trends and discuss version {{ "4.2.1" | cast_pronounce: "version" }} of the platform. Your account ID is {{ "738291" | cast_pronounce: "number_pair" }}. {%- endcapture -%} {{ narration | cast_pronounce: "all" }} ``` What happens: 1. The `capture` block builds the narration, applying `version` and `number_pair` patterns to the specific values 2. The entire captured text is then passed through `cast_pronounce: "all"`, which finds CSM, QBR, and NPS and substitutes their dictionary entries **Screen shows:** ``` Your CSM has prepared your QBR materials. We'll review your NPS trends and discuss version 4.2.1 of the platform. Your account ID is 738291. ``` **Narrator says:** ``` Your Customer Success Manager has prepared your Quarterly Business Review materials. We'll review your Net Promoter Score trends and discuss version 4 point 2 point 1 of the platform. Your account ID is 73 82 91. ```

What’s Next

In Module 11, you’ll learn about the two remaining Cast custom filters: cast_highlight for visual emphasis and cast_footnote for adding reference notes that aren’t read aloud.

đź“– Official documentation:

  • Custom Cast Filters: https://school.cast.app/liquid/custom-cast-filters.html#cast_pronounce
  • Pronunciations setup: https://school.cast.app/personalizing-content/pronunciations.html
This site uses Just the Docs, a documentation theme for Jekyll.