Docs

Install it, make sound from Python or the command line, or add it to a web page.

Quick start

pip install lipservice

Version 0.1.0. One package with no third-party dependencies, for Python 3.9 or later on macOS and Linux. The first call fetches the models (see Voices and models) and keeps them.

Python

import lipservice as lip

lip.say("Hello from your own CPU.").save("hello.wav")
lip.say("And now, a little faster.", voice="ben", rate=1.15).save("ben.wav")
lip.sing("bpm 90\nTwinkle C4:1 C4:1\ntwinkle G4:1 G4:1\n", voice="cora").save("star.wav")

Command line

lipservice voices
lipservice say "Hello from your own CPU." -o hello.wav
lipservice sing song.txt --voice cora -o song.wav

Sound comes out as 24 kHz mono WAV. Without -o it is played. Both say and sing take quality="hifi" (the default) or "fast": hifi sounds better; fast is about twice as quick. The README on GitHub lists every option.

Embed it in a page

One line adds a Listen button that reads your page aloud. The engine and its voice download from https://lipservice.dev and run in the visitor's browser.

<script type="module" src="https://lipservice.dev/embed.js"></script>

It reads the page's main or article, block by block, and marks what it is reading. To speak a single passage instead, put it in a lipservice-speak element, which shows its own button:

<lipservice-speak voice="ben">Hello from your own computer.</lipservice-speak>

The first press downloads the 1.1 MB engine and 56 MB of models; the browser keeps them for the next visit.

SSML

Lip Service reads the core of W3C SSML 1.1. A tag or attribute it cannot honor is an error that names it; nothing is silently skipped.

elementattributes and values
speakthe root; xml:lang, when given, English
p, sa sentence ends with a full stop; a paragraph also with a strong break
breaktime="500ms" or "2s", or strength: none, x-weak, weak, medium, strong, x-strong
prosodyrate: x-slow to x-fast, "80%", "+20%" or a multiple; pitch: x-low to x-high, "+2st", "+10%" or "180Hz"; volume: silent, x-soft to x-loud, or "+3dB". Nested rates multiply; semitones and decibels add.
emphasislevel: strong, moderate (the default), none or reduced
say-asinterpret-as: characters or spell-out, cardinal or number, ordinal, digits, time
phonemealphabet x-arpabet, arpabet or cmu; ph said as one word
subalias said in place of the text
langEnglish only
w, tokena word or words, as the text says them
meta, metadatanot said
<speak>The key is under the mat. <break time="400ms"/>
<prosody rate="slow" pitch="-2st" volume="soft">Don't tell anyone.</prosody></speak>

Without SSML, a yes/no question rises at its end, and numbers, dates, times, money and abbreviations are read the way a person reads them.

Song format

A song is plain text, a line each:

# Twinkle, Twinkle, Little Star (traditional)
bpm 100
twinkle C4:1 C4:1
twinkle G4:1 G4:1
little A4:1 A4:1
star G4:2

The melody is sung at the written pitch. For a man's voice, shift it an octave down: shift=-12 in Python.

The editor's files

The editor saves two kinds of file, both plain text you can read and change by hand. A part is one singer: the voice and its settings, the tempo, and every note with its start, length, pitch and syllable, plus the vibrato drawn under the notes and any breath marks. A score is several singers together: the master level and effects, then each singer's level and pan, followed by that singer's whole part. When you press Sing, the editor writes each part out in the song format above: it joins the syllables into words, turns the gaps between words into rests, and keeps each note's length. A part also keeps what a song has no line for, such as tempo changes and each note's key velocity, so a file opens again exactly as it was saved.

A part's first line is lipservice part 2; a score's is lipservice score 1. Inside a score each singer's part begins with its own lipservice part 2 line, so a part lifted out of a score is a part's file. The full reference is in the repository: PART.md and SCORE.md. The editor also opens and saves MIDI files.

Voices and models

Sixteen voices ship: Ada, Ben, Cora, Dev, Eve, Finn, Gwen, Hal, Ivy, Jack, Kate, Leo, Mae, Ned, Opal and Pete. Each is one .lsw file, loaded beside the shared models.

A first reading needs 56 MB of models on hifi and 52 MB on fast. Each further voice is 0.4 MB.

On this site the quality is chosen beside the voice. A phone starts on fast, where singing a choir in hifi may not keep up with playback. A choir measures how fast this device sings, and a later choir is sung on fast where hifi was slower than it plays. Whatever you choose is kept for your next visit.

The Python package fetches the models from models.lipservice.dev, checks each file against the size and SHA-256 it carries, and keeps them in ~/Library/Caches/lipservice on macOS or ~/.cache/lipservice on Linux (LIPSERVICE_CACHE moves it). To work offline, run lipservice fetch first, or point LIPSERVICE_MODELS at a folder that holds them.

Questions

Does it need a GPU?

No. It runs on one CPU core, faster than real time.

Which browsers does it run in?

Browsers with WebAssembly SIMD and AudioWorklet: current Chrome, Edge, Firefox and Safari.

Which languages does it speak?

English today.

Can I use it in a commercial product?

Yes. Under the AGPL if you meet its terms, or under a commercial license if you ship it closed. See licensing.