Creating Content for Waclaw Says

Waclaw Reads supports two content formats: .ws files (single-language, multi-speaker audio scripts) and .xml files (lists of .ws files, like chapters in a book).

Download this guide as Markdown

The .ws Format

A .ws file is a UTF-8 JSON document with this structure:

{
  "version": 1,
  "title": "Chapter Title",
  "language": "en-US",
  "speakers": {
    "id1": { "name": "Speaker Name", "hint": "male" },
    "id2": { "name": "Another Speaker", "hint": "female" }
  },
  "segments": [
    { "speaker": "id1", "text": "First line of dialogue." },
    { "speaker": "id2", "text": "Response." }
  ]
}

Field Reference

Field	Type	Description
`version`	int	Schema version — must be `1`
`title`	string	Display title for the file
`language`	string	BCP-47 language tag (e.g. `en-US`, `pl-PL`)
`speakers`	object	Map of speaker ID → speaker object. At least one required.
`segments`	array	Ordered list of spoken lines. At least one required.

Speaker Object

Field	Type	Description
`name`	string	Display name shown during playback
`hint`	string	Gender hint: `male` or `female`. Any other value is rejected.

Segment Object

Field	Type	Description
`speaker`	string	Must reference a key defined in `speakers`
`text`	string	The spoken text. Must be non-empty.

Rules

Every segment must declare its speaker explicitly — no implicit inheritance.
Speaker IDs are case-sensitive.
Unknown speaker references or invalid hint values will cause the file to be rejected.
The file must contain at least one speaker and one segment.

Tip: Use short speaker IDs like n, a, b for concise files. The display name is what matters to the listener.

The .xml Format

An .xml file is an ordered list of .ws URLs, like chapters in a book:

<?xml version="1.0" encoding="UTF-8"?>
<waclawList version="1">
  <title>My Book Title</title>
  <item>
    <title>Chapter 1</title>
    <url>https://example.com/ch1.ws</url>
  </item>
  <item>
    <title>Chapter 2</title>
    <url>https://example.com/ch2.ws</url>
  </item>
</waclawList>

Rules

Root element must be <waclawList> with version="1".
<title> at the root level is the list title shown in the library.
Each <item> must have a <title> and a <url>.
URLs must point to .ws files and use https://.
At least one <item> is required.
Order in the XML determines display and playback order.

Tip: Use relative URLs when your .ws files are on the same server: /ls.ws instead of https://example.com/ls.ws.

Example: Multi-Speaker Story

Here is a short sample .ws file with dialogue between two characters:

{
  "version": 1,
  "title": "A Short Story",
  "language": "en-US",
  "speakers": {
    "alice": { "name": "Alice", "hint": "female" },
    "bob": { "name": "Bob", "hint": "male" }
  },
  "segments": [
    { "speaker": "alice", "text": "Good morning! How are you today?" },
    { "speaker": "bob", "text": "I'm fine, thanks. What did you do yesterday?" },
    { "speaker": "alice", "text": "I went for a walk in the park. The weather was beautiful." },
    { "speaker": "bob", "text": "That sounds lovely. I should get outside more often." }
  ]
}

Language Support

Waclaw Reads uses the device's built-in TTS engine. Available languages depend on what is installed on the user's device. Common BCP-47 tags:

en-US — English (United States)
en-GB — English (United Kingdom)
pl-PL — Polish (Poland)
de-DE — German (Germany)
es-ES — Spanish (Spain)

Note: If no suitable voice is available for the file's language, the app falls back to English. If no English voice exists, playback will fail.

Download this guide as Markdown