Exporting audio and subtitles

Export audio, in the reader's File menu, and tw export-audio, from a terminal, render a document as speech in an audio file for later listening on a phone, a music player, or an audiobook player. The output may be a WAV, FLAC, MP3, Opus, or Ogg Vorbis file, or an M4B audiobook; each carries one chapter per heading. An MP4 video that displays the text with the spoken word marked is also available. Subtitle files can accompany any export, with a caption for each sentence or each word at the moment it is spoken. Typical uses are an audiobook of a week's reading assignments, or captions that follow spoken text for a class.

Export audio from the reader comes first. The rest of the guide concerns tw export-audio, whose settings the reader shares; each task section opens with the command and then explains it.

Export audio from the reader

In the reader, open the File menu (F10 in the terminal) and choose Export audio, or find "Export audio" in the command palette. A document must be open. Export audio is in the terminal reader, the app, and tw in every release; only a lean build of the reader, made with --no-default-features, leaves it out (Building).

The format. You hear, for example, "Export essay as audio: choose a format, 6 choices." FLAC comes first: lossless and about half the size of WAV. MP3 follows: small, and every player opens it. Then Opus: the smallest, made for speech. Then Ogg Vorbis: small and open, and most players open it. Then WAV. M4B and "Video with captions: MP4, needs ffmpeg" are listed only when ffmpeg is installed; when it is not, textweaver first offers to fetch it (a no, or a system with no build to fetch, goes on), and then you hear "M4B, MP4 need ffmpeg, which was not found." (see Make a video with captions). Last comes "Read-along page: text and audio, one file", which writes essay.html (see Make a read-along page). Press Enter on a format. The format in the [export] audio_format setting (Settings, Audio export format) is listed first; FLAC unless you change it.
Where. "Where should the audio go?" The first choice puts the file beside the document, with the document's name, such as essay.flac. The second opens the file browser to choose another folder: press Ctrl+Enter on the folder, or Enter on its "Choose this folder" row (see Choosing a folder).
The question. "Export essay.flac with Microsoft David at 200 words per minute, into D:\Notes? y or n". It names the voice and the speed the export uses: your current voice and rate. Press y to start, or n to cancel.

The export runs in the background, so reading can continue. Progress is announced in steps of ten percent, for example "Exporting audio, 30 percent.", at most once every ten seconds, and the interface announcements setting can quiet these. Nothing plays through the speakers.

To stop, press Escape with no list or question open. You hear "Stop the export? No file is kept. y or n". Press y, and the export stops after the sentence being read; no file is left behind.

At the end you hear, for example, "Wrote essay.flac: 42 minutes and 5 seconds, 12 chapters. Open it? y or n" Press y to open the file in your default player. If another list or question is open then, you hear the result without the question.

The engine is chosen in this order: the current reading engine, when it can write audio files; otherwise the one in the [speech] backend setting, when it can; otherwise the best installed engine that can. Engines that can only speak aloud, such as Omnivox, are never used. The export uses the document as it was last opened, so in edit mode, save and leave edit mode first to include recent changes.

Before you start

Two things are required: a voice that can write audio files and, for M4B audiobooks and MP4 videos only, the free program ffmpeg. WAV, FLAC, MP3, Opus, and Ogg Vorbis need nothing further.

Check that you have a voice that can write files

tw backends

This lists the speech engines textweaver knows about. An engine that can write files includes "audio files" among its supported capabilities, for example:

sapi: Windows SAPI5 voices. Available. Priority 500. Supports word highlighting, pause, pitch, volume, audio files, and tones. Word timing from the engine.

These engines can write files: ETI-Eloquence (eci), Windows SAPI5 voices (sapi), DECtalk (dectalk), eSpeak NG (espeak), and the two Apple engines on macOS (nsspeech and avspeech). Omnivox (omnivox) and Speech Dispatcher (speechd) can only speak aloud, so they cannot export. The silent engine (null) cannot export either.

WAV, FLAC, MP3, Opus, and Ogg Vorbis always work

textweaver writes WAV, FLAC, MP3, Opus, and Ogg Vorbis files itself, with no external program.

WAV files are large, but every player can open them.
FLAC files are about half the size of WAV, with exactly the same sound (FLAC is lossless). Most music and audiobook players on phones and computers can open them.
MP3 files are small, and every player can open them. textweaver encodes them with the built-in LAME encoder at variable bit rate, quality 5, which suits a speaking voice. LAME is free software under the GNU LGPL; THIRD-PARTY-NOTICES.md describes the terms.
Opus files are the smallest of all: about 14 MB for an hour of speech, a quarter of the MP3. textweaver encodes them with libopus, the reference Opus encoder, built in: one channel at 32 kilobits per second, as an Ogg Opus file (.opus). Most phones, browsers, and VLC play them; some older car stereos and music players do not. libopus is free software under a BSD license.
Ogg Vorbis files (.ogg) are small, and use an open format that most players, browsers, and VLC open, including some that do not play Opus. textweaver encodes them with libvorbis, built in, at quality 3 (the usual default of the oggenc tool), keeping the voice's own sample rate and channels. libvorbis and libogg are free software under a BSD license.

M4B needs ffmpeg

To write .m4b or .mp4, textweaver first writes a WAV and then has ffmpeg convert it. textweaver does not bundle ffmpeg. Where its publisher provides a build for the platform (Windows and Linux), textweaver offers to fetch it when Export audio is started without it, naming the size and license and asking first (Optional components). On macOS, or if you prefer, install ffmpeg yourself, or obtain it from your own components source (see Optional components).

textweaver searches for ffmpeg in three places, in this order:

The TEXTWEAVER_FFMPEG environment variable, if it is set. It must be the full path to the ffmpeg program.
textweaver's components folder, components in the data folder, where a copy that textweaver fetched, or one from a components source, goes.
Otherwise, a program named ffmpeg in one of the folders on your PATH, which is where installers put it.

Install ffmpeg on Windows

If textweaver fetched ffmpeg at your request, nothing more needs installing. To install it manually, use the Windows package manager, winget:

winget install Gyan.FFmpeg

When the installation finishes, open a new terminal window so that the updated PATH is read, then confirm that ffmpeg is found:

ffmpeg -version

The output begins with "ffmpeg version". If the command is not recognized, see If something goes wrong.

Install ffmpeg on macOS

With Homebrew installed, run:

brew install ffmpeg

Install ffmpeg on Linux

Use your distribution's package manager. The package is usually called ffmpeg. For example, on Debian or Ubuntu:

sudo apt install ffmpeg

Tell textweaver where ffmpeg is

This is needed only when ffmpeg is installed in a folder that is not on the PATH. In PowerShell, for the current session:

$env:TEXTWEAVER_FFMPEG = "C:\Tools\ffmpeg\bin\ffmpeg.exe"

In a Linux or macOS shell:

export TEXTWEAVER_FFMPEG="$HOME/tools/ffmpeg"

When TEXTWEAVER_FFMPEG is set, textweaver uses only that path and does not search PATH. If the path is wrong, textweaver reports that ffmpeg was not found, even when ffmpeg is on the PATH.

Export a document to a WAV file

tw export-audio reading.md --out reading.wav

This renders reading.md as speech into reading.wav without playing it through the speakers. Any document textweaver can open may be exported, not only Markdown.

The document is rendered exactly as textweaver would read it aloud: with the same rate, pitch, volume, and normalization settings and the same announcements, such as "heading level 1". The sentences are written in sequence into a single file.

The output format comes from the file name you give with --out:

.wav: a WAV file. Always works.
.flac: a FLAC file. Always works; textweaver writes it itself.
.mp3: an MP3 file. Always works; textweaver encodes it itself with the LAME encoder, at variable bit rate, quality 5.
.opus: an Ogg Opus file. Always works; textweaver encodes it itself with libopus, in one channel at 32 kilobits per second, at 48 kHz (the voice's audio is converted to that rate).
.ogg: an Ogg Vorbis file. Always works; textweaver encodes it itself with libvorbis, at quality 3, at the voice's own sample rate.
.m4b: an M4B audiobook (AAC audio at 64 kilobits per second). Needs ffmpeg.

The extension is not case-sensitive, so .MP3 works too. Any other extension is refused before anything is read. A name with no extension, such as --out reading, receives the format in [export] audio_format, FLAC by default, so reading.flac is written.

If the output file already exists, it is replaced without asking.

What you hear while it works

Progress is reported in steps of ten percent, one short sentence each, so that a screen reader is not flooded, for example "10 percent done." A message is issued only when a new step is reached at the end of a sentence, so a short document skips some steps.

On completion, one sentence reports the result, followed by a second when subtitles were written. This is an actual result from a short document with two headings:

Wrote reading.wav: 9 seconds, 7 sentences, 2 chapters, with Recording (test double). Subtitles in reading.srt.

The sentence says:

The file written.
The length of the audio, in words, such as "1 hour, 2 minutes, 5 seconds".
How many pieces were read. Headings count, so a document with two headings and five sentences gives "7 sentences".
How many chapters were found.
The engine used. "Recording (test double)" is textweaver's test engine; with a real voice you hear its engine name, such as "Windows SAPI5 voices", "ETI-Eloquence", "DECtalk", or "eSpeak NG".

Progress messages go to the error output and the result sentence to the standard output, so the two can be redirected separately.

Control C stops an export. A partly written file may remain; delete it and start again.

Make a pocket review

Notes and highlights can also be taken along as audio. First export a study sheet (press F2 and type export study sheet; see notes), which writes essay-study-sheet.md beside essay.md, then render the sheet as speech:

tw export-audio essay-study-sheet.md --out essay-review.mp3

MP3, FLAC, Opus, and Ogg Vorbis need nothing further. With ffmpeg installed, --out essay-review.m4b produces an audiobook with a chapter for each heading of the essay, so a book player can move between sections. tw convert essay-study-sheet.md --to brf produces a braille copy of the same sheet. Thirty highlights amount to about 3,000 words, or about 15 minutes of audio at 200 words a minute.

Make an audiobook with chapters

tw export-audio "Chapter 3.docx" --out "Chapter 3.m4b"

This writes an M4B audiobook, a single file with chapters. Audiobook players open it, remember the listening position, and navigate by chapter.

The M4B file also carries:

The document's title, as the title and the album.
The document's author, when the document names one, as the artist.
The genre "Audiobook".
One chapter for each heading, with the heading as its name.

While ffmpeg runs, and while a FLAC, MP3, Opus, or Ogg Vorbis file is encoded, textweaver keeps the full WAV (and, for ffmpeg, a small metadata file) in a hidden folder beside the output whose name begins with .textweaver-export-. The folder is removed when the export finishes. Enough free disk space must be available for the full WAV, which is much larger than the finished M4B.

How chapters are chosen

Every heading, at every level from 1 to 6, starts a chapter. The chapter's name is the heading's text (up to 200 characters).
Every section break also starts a chapter: in an EPUB, each file of the book; in a Word document, each section. When a section starts with a heading, the two make one chapter, named by the heading. A section without a heading is named by its label, or "Chapter 1", "Chapter 2", and so on when it has none.
Text before the first heading becomes its own first chapter, named after the document's title, or "Audiobook" when the document has no title.
A document with no headings at all is one chapter.
A heading with no audio of its own, for example two headings read in one piece, is left out.
Each chapter starts at the moment its heading is reached in the audio, measured, not estimated.

There is no option yet to choose which heading levels make chapters.

Chapters in FLAC, MP3, Opus, Ogg Vorbis, and WAV files

tw export-audio "Chapter 3.docx" --out "Chapter 3.flac"

Every format carries the same title, author, and chapters as the M4B, each in its own kind of tag:

FLAC files: as Vorbis comments. The title is TITLE and ALBUM, the author is ARTIST, and each chapter is a pair, such as CHAPTER001=00:01:30.250 for its start and CHAPTER001NAME=Light for its name. Audiobook players that read FLAC chapters show them.
Opus and Ogg Vorbis files: as the same Vorbis comments as FLAC, in the file's comment header.
MP3 files: as ID3 chapter tags (CHAP and CTOC), with the title, artist, album, and genre.
WAV files: as ID3 chapter tags too, in an extra part of the file that players without ID3 support skip.

Players that support these tags display the chapters; many simple players ignore them and play the file straight through. The JSON report lists each chapter's name, start, and end in every case (see Get a report as JSON).

Make a read-along page

tw export-audio essay.md --out essay.html

An .html file name writes a read-along page instead of an audio file: a single web page that holds the document as real text, with its audio embedded as MP3 and a mark on the sentence and word being read as it plays. It opens in any web browser and needs no internet connection and no other file, so it can be sent, posted to a course site, or opened on a phone. In the reader, choose File, Export as, Read-along page: text and audio, or type read-along in the command palette; you are asked only where it goes. It is also "Read-along page: text and audio, one file", the last format in Export audio.

The text remains text, so screen readers, Braille displays, zoom, reflow, and custom fonts all work with it. The page uses the reading theme ([display] theme); with the default theme it follows the system's light or dark setting.

The audio control. The browser's own player, at the top of the page.
The buttons. Play (Pause while playing), Back a sentence, Forward a sentence, and Follow along. Tab reaches each one; Enter or Space presses it.
Follow along. On by default: the page scrolls to keep the sentence being read in view. Press it to turn scrolling off; a screen reader says "pressed" or "not pressed". With reduced motion set in the system, the page jumps instead of scrolling smoothly.
Speed. A list from 0.75 to 2 times.
Contents. For a document with chapters, a "Play section" button for each, such as "Play section: Photosynthesis".
Click a sentence to start reading there.
What you see. The sentence being read is underlined and tinted; the word being read is bold, underlined, and outlined in the theme's spoken-word colors. In a forced-colors (high contrast) mode the word uses the system highlight colors. Color alone never carries the mark.
With a screen reader. The page never moves your focus and never speaks on its own, so your screen reader reads where you are while the audio plays.
Without scripts. The text and the audio control still work; only the buttons and the marks are missing.

The page is about a third larger than the MP3 would be on its own. The subtitle and chapters settings work as for audio files.

Make a video with captions

tw export-audio essay.md --out essay.mp4

An .mp4 file name writes a karaoke video: the document read aloud, with the current sentence on screen and the current word in bold and underlined. It suits playing a reading on a class screen, posting it to a course site, or watching it on a phone. In the reader, choose "Video with captions: MP4, needs ffmpeg" in Export audio. It needs ffmpeg, like M4B (see M4B needs ffmpeg): without ffmpeg the format is not listed, and you hear "M4B, MP4 need ffmpeg, which was not found."

What you see. A 1280 by 720 picture in your reading theme's page and text colors ([display] theme), in the bundled Atkinson Hyperlegible Next font. The whole sentence is shown, wrapped to fit; a very long sentence shows the lines around the word being read. The spoken word is bold and underlined, so the mark is a shape, never a color.
The captions. The video carries the WebVTT captions as a soft subtitle track, which players can turn on and off and screen readers in some players can read. They are the same caption lines as --subtitles essay.vtt.
The chapters. One chapter for each heading, as in an M4B, so players with a chapter list can jump.
The sound. AAC at 96 kilobits per second.
The picture. H.264, with ffmpeg's libx264 encoder when it has one, otherwise the system's own H.264 encoder that ffmpeg offers (Media Foundation on Windows, VideoToolbox on macOS), otherwise OpenH264, and as a last resort MPEG-4. The picture changes only when the spoken word changes, ten times a second at most, so the file stays small: a little more than the M4B would be.
How long it takes. textweaver reads the whole document first, as for any audio file, then draws the frames and has ffmpeg encode them. The encode takes a few minutes for an hour of speech. While it runs, a progress message comes at most every ten seconds, with the frames sent to ffmpeg and an estimate of the time left, worked out from how fast the frames have gone so far: for example, "Encoding video: 1000 of 9000 frames, about 2 minutes left." The reader and tw export-audio both give it, and --quiet leaves it out. A stop during the encode is honored: ffmpeg is stopped and no file is left behind.

--subtitles and --chapters still write their own files beside the video.

Add subtitles

tw export-audio reading.md --out reading.wav --subtitles reading.srt

This writes the audio and, beside it, a subtitle file. The format is determined by the extension given to --subtitles:

.srt: SubRip, the most widely supported format.
.vtt: WebVTT, the format web pages use. The file starts with the line WEBVTT.
.ass: Advanced SubStation Alpha, with karaoke by outline (see Karaoke subtitles).

Any other extension is refused with a message, before any audio is made.

Subtitles work with every audio format, so --subtitles can be combined with .wav, .flac, .mp3, or .m4b. If the subtitle file has the same name as the audio file apart from its extension, most players load it automatically.

This is the start of the real SRT file from the example above:

1
00:00:00,750 --> 00:00:01,000
Photosynthesis

2
00:00:01,000 --> 00:00:02,250
Plants make food from light.

3
00:00:02,250 --> 00:00:03,750
They need water and carbon dioxide.

How captions are made:

Each sentence gets its own caption. Its start and end are measured from the audio, so captions stay in step with the voice even at the end of a long book.
A long sentence is split into several caption lines. A line holds at most 12 words and at most 90 characters.
Captions show the document's own text, not the words the voice says. A price written "$5" and read "five dollars" is captioned "$5".
Things that are spoken but are not in the document have no caption. In the example, the voice says "heading level 1" before "Photosynthesis", so that caption starts a little after the audio does.
A caption never ends before it starts; a caption with no length is given 50 milliseconds.

One subtitle per word

tw export-audio reading.md --out reading.wav --subtitles reading.vtt --word-level

--word-level gives each word its own cue instead of whole caption lines, which suits tools that highlight one word at a time. The following is the start of the actual WebVTT file from the example document, without its NOTE block (see The note in each subtitle file):

WEBVTT

00:00:00.750 --> 00:00:01.000
Photosynthesis

00:00:01.000 --> 00:00:01.250
Plants

00:00:01.250 --> 00:00:01.500
make

Punctuation stays with its word, so the last word of a sentence reads "light." rather than "light".

Which engines time each word exactly

Some engines report the exact moment each word sounds in the file, and with them word cues are exact. These engines are:

ETI-Eloquence through textweaver's own Eloquence support (eci).
Windows SAPI5 voices (sapi), except Code Factory's Eloquence voices through SAPI, which report no word times.
DECtalk (dectalk).
eSpeak NG (espeak).
Apple's AVSpeechSynthesizer (avspeech) on macOS 14 and later, which reports where each word starts in the audio it writes.

The classic Apple engine (nsspeech) and the SAPI Eloquence voices can write files but do not report word times, so their word cues are estimated: each sentence's start and end are still measured, and the interval is divided among its words in proportion to their length. Sentence captions from these engines are as accurate as from any other, because they depend only on the measured sentence times.

Karaoke subtitles

Karaoke subtitles show the whole caption line and mark the word being read. The mark is always a shape (an underline, bold and underline, or an outline) and never depends on color alone. There are three styles.

Underline as spoken (--karaoke tags, WebVTT only):

tw export-audio essay.md --out essay.mp3 --subtitles essay.vtt --karaoke tags

Each word after the first in a line gets a timestamp tag, and a STYLE block underlines the words already spoken. Players that do not understand the tags show the plain line. SRT has no tags, so an SRT file stays plain. An illustration, for a document titled Photosynthesis with no heading, read at an even 250 milliseconds a word:

WEBVTT

STYLE
::cue(:past) {
  text-decoration: underline;
}

NOTE
Photosynthesis. Read by Recording (test double), 240 words a
minute. Made by textweaver.

00:00:00.000 --> 00:00:01.250
Plants <00:00:00.250>make <00:00:00.500>food <00:00:00.750>from <00:00:01.000>light.

One cue per word (--karaoke lines, WebVTT or SRT): every word gets its own cue showing the whole line, with that word in bold and underline. This works in the most players, YouTube included. A player that reads or brailles each cue repeats the line once per word, so it is never the default.

00:00:00.000 --> 00:00:00.250
<b><u>Plants</u></b> make food from light.

00:00:00.250 --> 00:00:00.500
Plants <b><u>make</u></b> food from light.

ASS karaoke (--subtitles essay.ass): an Advanced SubStation Alpha file for players built on libass, such as mpv and VLC. Unread words are white with no outline; each word gains a 3 pixel black outline and turns yellow as it is reached. The \ko tag carries each word's time in hundredths of a second.

--word-level takes precedence over --karaoke: each cue holds one word, with no surrounding line.

The note in each subtitle file

Every WebVTT file textweaver writes now starts with a NOTE block that players do not show: the title, the voice and engine, the rate in words a minute, and "Made by textweaver." An ASS file has the same line as a comment and the title as its Title. The language belongs to the player's track settings, not the file, so it is not written.

Write a chapters file

tw export-audio essay.md --out essay.mp3 --subtitles essay.vtt --chapters essay.chapters.vtt

This additionally writes a WebVTT chapters file with one cue per chapter, the chapter's title being its text; web players use it for a chapter menu. The chapters are the same ones written into an M4B. A document with no headings has one chapter named after its title. When it has no title either, the chapter is named in the interface language ("Audiobook", "Hörbuch", "Audiolibro" and so on), and untitled chapters are numbered the same way ("Chapter 2", "Kapitel 2").

Choose the engine, voice, rate, and pitch

tw export-audio reading.md --out reading.mp3 --backend sapi --voice David --rate 200 --pitch -2

Each option is optional:

--backend: the engine, by its id from tw backends, such as eci, sapi, dectalk, or espeak.
--voice: a voice, by its id or its name. Words from the name are enough: "David" finds "Microsoft David Desktop". tw voices --backend sapi lists the voices of an engine.
--rate: the speaking rate in words per minute, from 50 to 900. Values outside that range are brought inside it.
--pitch: a pitch change in semitones, from -12 to 12. A negative number lowers the voice.

Without --backend, textweaver chooses in this order:

The engine in your [speech] backend setting, if it is installed and can write files.
Otherwise, the best installed engine that can write files: ETI-Eloquence first, then Windows SAPI5 voices, DECtalk, the Apple engines, and eSpeak NG. Engines that can only speak aloud are passed over.

If the engine you name with --backend is not installed, textweaver chooses automatically instead. When that works, you hear, for example, "Backend eci is not available; using sapi." after the result.

Without --voice, textweaver uses your [speech] voice setting, but only when the chosen engine is the one in your [speech] backend setting, because a voice belongs to its engine. Otherwise the engine's own default voice is used.

Settings the export reads

tw export-audio reads the settings, so the audio sounds as textweaver reads aloud. These settings are used:

[speech] backend and [speech] voice, as described above.
[speech] rate and [speech] pitch. The --rate and --pitch options override them for this export.
[speech] volume. There is no option for it; change the setting.
[speech] punctuation and [speech] split_caps: how much punctuation is spoken, and whether capitals inside words are spoken separately.
[speech] skip_code: whether code blocks are left out (off by default, so code is read).
[speech] verbosity: how much structure is announced. At low, headings are not announced as "heading level 1".
[normalization]: numbers, abbreviations, your pronunciations, math, and the community lexicon, the same as when reading aloud. Engines that read numbers and abbreviations themselves, such as ETI-Eloquence, are left to do so.
[normalization] table_mode: tables read with row and column context (structured), as cell text only (flat), or left out (skip).
[normalization] footnote_mode: footnotes read where they are referenced (inline), at the end of the section (deferred), or left out (skip).
[export] audio_format: the format written when --out has no extension.
The three [export] subtitle settings, described next.

See the settings guide for how to look at, export, and import your settings.

Write subtitles every time

tw settings import export-settings.toml

The [export] settings produce subtitles without requiring --subtitles on each run. Place them in a small TOML file, such as export-settings.toml, and import it; import changes only the settings the file names. Adding --dry-run first reports what would change.

[export]
subtitles_with_audio = true
subtitle_format = "vtt"
subtitle_word_level = false
subtitle_karaoke = "off"
subtitle_chapters = false

The settings:

subtitles_with_audio: true or false. The default is false. When true, every export also writes subtitles next to the audio, with the same name and the subtitle format's extension. Exporting book.mp3 then also writes book.srt.
subtitle_format: "srt", "vtt", or "ass". The default is "srt". It is used only for the file subtitles_with_audio names. A file you name with --subtitles always uses its own extension.
subtitle_word_level: true or false. The default is false. When true, subtitles always have one cue per word, as if you had added --word-level.
subtitle_karaoke: "off", "tags", or "lines". The default is "off". It is the karaoke style when you do not give --karaoke.
subtitle_chapters: true or false. The default is false. When true, every export also writes a chapters file beside the subtitles (or beside the audio when there are none), named like it with .chapters.vtt: book.vtt gives book.chapters.vtt.

A file named with --subtitles always wins over subtitles_with_audio. --word-level turns word cues on even when subtitle_word_level is false; there is no option to turn them off for one export when the setting is true.

These settings are used by tw export-audio and by Export audio in the reader, which writes subtitles beside the audio when subtitles_with_audio is true, with the karaoke style of subtitle_karaoke, a chapters file when subtitle_chapters is true, and a note naming the voice and the rate.

Get a report as JSON

tw export-audio reading.md --out reading.wav --json

--json prints a full report instead of the result sentence, for scripts and other programs. Progress messages are omitted, as with --quiet. The report has two parts.

backend says which engine was used:

backend: the engine's id, name, priority, whether it is opt_in (used only when named) and available, and its capabilities (caps).
requested: the engine you named, or null.
fell_back: true when the engine you named was not available and another was chosen.

export says what was written:

out: the audio file.
format: wav, flac, mp3, opus, ogg, m4b, or mp4.
subtitles: the subtitle file, or null.
ffmpeg: the ffmpeg program used for M4B or MP4, or null.
timeline: everything about the audio.

timeline holds:

duration_ms: the length of the audio in milliseconds.
title and author: from the document, or null.
chapters: each chapter's title, start_ms, end_ms, and source_start (where it starts in the document, in characters).
sentences: each piece read, with start_ms and end_ms; source, its place in the document; text, its caption (the document's text); spoken, what the voice actually said (for a heading, for example "heading level 1, Photosynthesis"); and words.
words: for engines that report word times, each word's start_ms, end_ms, source, caption (its place in the caption text), and text. The list is empty for engines that do not report word times.

Quiet output

tw export-audio reading.md --out reading.m4b --quiet

--quiet omits the progress messages; the result sentence and any error are still reported.

Use settings from another folder

tw export-audio reading.md --out reading.wav --home "E:\textweaver"

--home reads settings from the named folder instead of the usual location, in the same way as the TEXTWEAVER_HOME environment variable. The settings file is config\settings.toml inside that folder. This suits a portable copy of textweaver on a USB stick, or trying settings without changing the usual ones.

If something goes wrong

Every problem is reported as one sentence beginning with "Error:". The messages below are the ones most likely to occur, with the remedy for each.

"Error: writing M4B needs ffmpeg, which was not found; install ffmpeg, set TEXTWEAVER_FFMPEG to its path, or export to .flac, .mp3, .opus, .ogg, or .wav". This is said before anything is read aloud. ffmpeg is not installed, or textweaver cannot find it. Install it as described in Before you start. If you just installed it, open a new terminal window. If TEXTWEAVER_FFMPEG is set, check that it is the full path to the program, including ffmpeg.exe on Windows, or remove the variable. Or export to .flac, .mp3, .opus, .ogg, or .wav, which need nothing.
"Error: cannot write notes.aac: use a .wav, .flac, .mp3, .opus, .ogg, or .m4b file name". Only WAV, FLAC, MP3, Opus, Ogg Vorbis, and M4B can be written. For a small file of speech, use .opus or .ogg.
"Error: The voice failed on sentence 1: engine error: the voice could not be used:" followed by the reason. The voice you chose could not be loaded, so nothing was written with another voice by mistake. Run tw voices --backend sapi and choose a voice from the list.
"Error: Cannot write subtitles to notes.txt: use a .srt, .vtt, or .ass file name." Give the subtitle file a .srt, .vtt, or .ass extension.
"Error: no installed voice can write audio files; install espeak-ng, or choose one with --backend". textweaver found no engine that can write files. Run tw backends and look for "audio files". On Windows, the SAPI5 voices usually can. On Linux, install eSpeak NG; see the speech guide.
"Error: Silent (no audio) cannot write audio files; choose another voice with --backend". The engine chosen cannot write files. The name at the start is the engine's, for example "Omnivox speech server". This also happens when you name an engine with --backend that is not installed and the automatic choice falls on an engine that cannot write files. Run tw backends, and name an engine that is available and lists "audio files".
"Error: cannot open reading.md", followed by the reason. The document was not found or could not be read. Check the name and folder. Put quotation marks around a name with spaces.
"Error: ffmpeg failed:" followed by ffmpeg's last message. ffmpeg itself could not convert the audio. Check that the output folder exists and that you can write to it, and that there is enough free disk space. Exporting to .wav shows whether the problem is in ffmpeg.
"Error: The voice failed on sentence 12:" followed by the engine's message. The engine stopped on that sentence. Try again, try another voice, or look at the sentence for unusual characters.
"Error: There is nothing to read aloud." The document has no text to read, for example a scanned PDF with only pictures of pages. Try tw text on the document to see the text textweaver finds.
"Error: The audio is too long for one WAV file; export a smaller part." A WAV file can hold at most 4 gigabytes, many hours of speech. Split the document into parts, for example one file per chapter, and export each one.
A message about the settings file, printed before the export starts. The export still runs. "Settings file was unreadable and has been reset to defaults" means the whole file was damaged: textweaver used the default settings, and the message says where it saved a backup copy. "Some settings were invalid and use their defaults" names the settings that were wrong; the rest of your settings were used. See the settings guide.