How to format a script so a line-learning app reads it

A line-learning app has to decide, for every line of text, who is speaking. Give it one speech per line, the character's name in capitals, a colon, then the words. Keep stage directions in brackets after the colon and delete everything else: page numbers, headers, directions on their own line. Most import problems come from those few rules.

Actors · drama students · teachers · 6 min read · rules checked in the app's code on 6 Oct 2026

Why apps misread scripts

A printed script is laid out for eyes, not for software. The name may sit centred above the speech, a speech may wrap over six lines, a page break may drop a page number into the middle of a sentence, and stage directions float between speeches. You see the structure at a glance; an app has to rebuild it from raw characters. When it guesses wrong, a speech goes to the wrong character, two speeches merge, or a line disappears. The fix is to remove the guessing.

The format MasteringTheatre reads

These rules come from the app's import code (Android and iOS share it), not from a help page.

1. One speech per line: NAME: text. A space before the colon is fine (HAMLET : To be…).
2. The name in capitals. Letters, spaces, full stops, apostrophes and hyphens are accepted: LADY MACBETH, MRS. ALVING, D'ARTAGNAN, MARY-JANE. Up to about 30 characters.
3. No digits in names. GUARD 2: is not read as a new speech. Write SECOND GUARD: or GUARD TWO:.
4. A colon, not a dash. Juliet: O Romeo (lower case) and HAMLET - To be (dash) are not split into new speeches.
5. Stage directions inside the speech, in brackets, after the colon. ALICE: (sitting down) You're late. The partner voice does not read the bracketed words and your score ignores them. A bracket before the colon, as in ALICE (entering):, stops the line being recognised.
6. Directions on their own line: delete them. The app either ignores them or glues them onto the speech above.
7. Scene headings: optional. A line such as SCENE 2, or a row of dashes ---, becomes a section you can tap to select that scene. Other headings are ignored or, like stray directions, glued to the speech above; delete them.
8. One spelling per character. KING and THE KING are two characters for the app.

The verse trap

If a speech wraps onto several lines, the app joins a following line to the speech above only when that speech does not yet end with a full stop, question mark, exclamation mark or closing quote (» or "), and when the line does not start with a word in capitals. Otherwise a line with no name is dropped. In verse, where a sentence often ends mid-speech, that silently loses lines. Two safe layouts: the whole speech on one line, or one beat per line with the name repeated each time. The second gives you a score per beat, which is the layout our monologue guide recommends.

SCENE 2
ALICE: You can't keep going like this,
Victor. It's been three weeks.
You haven't called once.
Victor — I'm not avoiding anything.
(silence)
ALICE: Really?
VICTOR (turning): Really.

SCENE 2
ALICE: You can't keep going like this, Victor. It's been three weeks. You haven't called once.
VICTOR: I'm not avoiding anything.
ALICE: (after a silence) Really?
VICTOR: (turning) Really.

Getting the text in: paste, file or photo

Length limit: 5,000 characters per import on the free plan, 100,000 on Pro and Premium. OCR and AI cleanup cost no energy. The file picker accepts .txt and .pdf only; save a Word document as PDF or plain text first. To test a PDF, try to select a sentence with your finger or mouse: if you can, the app can read it without OCR.

Free plan: the manual route

Without Pro you format by hand or with any general-purpose AI chat. Our free-plan tips page has a prompt to copy: paste your scene under it, ask for the result, check it, and paste that into the app. For a scanned page, ask the same chat to transcribe the photo first, then format the transcript. Check names and line breaks before you import; a chatbot can also “correct” words you meant to keep, so compare it with the original.

Check before the first run

• “Validate lines” greyed out: fewer than half of the non-empty lines look like NAME: text. Fix the layout, or run AI cleanup on Pro.
• “No lines detected”: no line has a capitalised name followed by a colon.
• Count the characters on the role screen. An extra character usually means two spellings of one name; a missing one usually means a lower-case or numbered name.
• Scroll your own speeches once. A speech that stops mid-sentence is the verse trap above.

Advice that works with most apps

We cannot vouch for how other apps parse text; their makers document their own formats, and some list screenplay formats such as Fountain or Final Draft. These habits help whatever you use:

• Keep a clean master copy in plain text. Re-importing from it is faster than fixing a bad import.
• Remove page numbers, running headers, and screenplay markers such as (CONT'D), (MORE) and CONTINUED.
• One speaker, one paragraph, the name written identically every time.
• Prefer a PDF with real text to a scan, and a flat, well-lit photo to an angled one.
• Cut to the pages you are working on. A shorter import is quicker to check.
• Look at what the app detected before you rehearse: names, number of speeches, the end of your longest speech.

What MasteringTheatre does not do

This page describes the app as it was on 2026-10-07. A score measures text accuracy, not talent. Published 2026-10-06 · updated 2026-10-07.