Docs
Install it, make sound from Python or the command line, or add it to a web page.
Quick start
pip install lipserviceVersion 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.wavSound 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>embed.js?button=noneleaves out the page's Listen button and keeps the element.embed.js?voice=adapicks the voice by its name (the list is under Voices and models).
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.
| element | attributes and values |
|---|---|
speak | the root; xml:lang, when given, English |
p, s | a sentence ends with a full stop; a paragraph also with a strong break |
break | time="500ms" or "2s", or strength: none, x-weak, weak, medium, strong, x-strong |
prosody | rate: 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. |
emphasis | level: strong, moderate (the default), none or reduced |
say-as | interpret-as: characters or spell-out, cardinal or number, ordinal, digits, time |
phoneme | alphabet x-arpabet, arpabet or cmu; ph said as one word |
sub | alias said in place of the text |
lang | English only |
w, token | a word or words, as the text says them |
meta, metadata | not 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:
bpm 90sets the tempo;rest 0.5rests for that many beats;- a word followed by one note per syllable, each
NOTE:BEATS(C4,F#3,Bb2); join notes with+to sing them on one syllable; vibrato 0.5 1:2, before a word, sets the vibrato from there on: each value is its size (1 the voice's own, 0 none), jumped to, or with:BEATSreached over that many beats;- lines starting
#are comments.
# Twinkle, Twinkle, Little Star (traditional)
bpm 100
twinkle C4:1 C4:1
twinkle G4:1 G4:1
little A4:1 A4:1
star G4:2The 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.