Say | SuperCollider 3.13.0 Help

Description

Say replaces the deprecated OSX speech synthesis used in SuperCollider, Speech. Because the underlying commandline program 'say' is quite different, Say does not work as a straight replacement, but instead allows access to the options of the 'say' program.

'say' is a commandline program in macOS, and thus does not generate sound on the server. Nonetheless, there are two ways to get say-based sound into SC servers:

1. Patching e.g. the system audio output to an audio input (by hardware of by software) and thus routing Say-produced (mono) sound into the server for processing.

2. Using the SayBuf class to render text as spoken soundfiles, and play those with buffers as full audio sources in SC.

macOS provides a wide variety of voices for many languages that you are free to install and use, see System Preferences/Accessibility/Speech.

Example files:// An example for premaking soundfiles for a piece: (Say.filenameSymbol.asString.dirname.dirname +/+ "saybuf_premake.scd").openOS; // Examples for synthdefs to make for say/saybuf: (Say.filenameSymbol.asString.dirname.dirname +/+ "saybuf_synthdefs.scd").openOS;

Which voices?Say.allVoices.size; // Say finds all installed voices Say.fxVoiceNames; // macOS has lots of effects voices - Say.fxVoices.size; // which are filtered out by default, such that: Say.voices.size; // voices just has the newer, better sounding voices. Say.voiceNames.size; // voices just has the newer, better sounding voices. // to remove and add voices from Say.voices, do ["Alex", "Kathy" ].do { |name| Say.removeVoice(name) }; Say.voices.size; ["Alex", "Kathy", "Bubbles" ].do { |name| Say.addVoice(name) }; Say.voices.size; // should be two fewer now: Say.voices.size; Say.voiceNames.size; Say.allVoiceNames.printAll;""; Say.fxVoiceNames.printAll;""; // each voice is a dict which has a name, a language name and short symbol, // and an example text: Say.allVoices.choose.cs;

Basic text reading methods// simple text reading methods "hi, this is the default voice speaking.".say; "hi, this is the first voice speaking.".say(0); "hi, this is a voice speaking that was selected by name.".say("Alex"); "hi, dies ist hoffentlich eine deutsche Stimme, ausgesucht durch die Sprache.".say(lang: \de); // each voice has a name, a language symbol, and an example text: v = Say.voices.choose; // say the example text of a specific voice: v.exampleText.say(v.name);

NEW Features in Say : (compared to Speech/speak)

1. .say any object:s.say; // "localhost" [1, 2, 3, 4].scramble.say(lang: \en); { SinOsc.ar }.say("Anna"); // "a Function" { SinOsc.ar }.cs.say("Anna"); // "{ SinOsc.ar }" Dictionary[\a -> 1, \b -> 2].say(lang: \en);

2. use events and patterns to create strings to be spoken :(type: \say, text: "hi there, i'm talking with the default voice now").play; (type: \say, text: "this is a random voice", voice: Say.voices.choose.name.postln).play; (type: \say, text: "Anna aus Doytschland, oder Standard-stimme", voice: "Anna").play; Pbind( \type, \say, [\voice, \text], Pseq( Say.voices.keep(10).collect { |vocdict| [vocdict.name, vocdict.exampleText].postln } ), \wait, true ).play; Say.killAll;

3. find and access voices by languages// list of all short lang symbols Say.allLangs.postcs // list of all long langName strings Say.allLangNames.postcs // you can use either of these to check whether a language is present, // or to get the list of the matching languages Say.isValidLang(\en) Say.voicesByLang("en") Say.isValidLang(\en_GB) // any British speakers in da house? Say.voicesByLang(\en_GB) // if yes, these ones Say.isValidLang("pt") // alguem que fala portugues? Say.voicesByLang(\pt).size // in my case, 3 voices Say.voicesByLang("pt").collect(_.langName) // in my case, -> [ pt_BR, pt_PT, pt_BR ] // one from portugal, 2 from brazil Say.isValidLang("pt_BR") // so brazilian portuguese is valid

4. find voices by name of language:Say.findVoice(0); // by index in allVoices Say.findVoice; // default is nil, becomes default system voice Say.defaultVoiceName; // you can ask which it is Say.findVoice(lang: \en); // random voice for a given language Say.findVoice(lang: \pt).postcs; // in my case, one of the 3 above Say.findVoice("Anna").postcs; // if German, this is present Say.findVoice("NoSuchVoice").postcs; // nonexisting voices become default voice

5. render spoken text to buffers, to use them as sound sources in SC:// text to be spoken, event for extra specs, action to do when buffer is ready SayBuf.prepare( (text: "this is a buffered voice", bufAction: { |b| b.play }) ) // see more examples in SayBuf.help; // say four words through buffers as quickly as possible: ( [\Multi, \Folder, \Sunny, \Beach].do { |txt| SayBuf.prepare((lang: \en, text: txt.asString, bufAction: { |b| txt.postln; b.play; })); }; )

Class Methods

.voices

the list of the available normal voices

.voiceNames

the list of names of the available normal voices

.allVoices

the list of all available voices

.allVoiceNames

the list of names of all available voices

.fxVoices

the list of the available fxVoices (the "funny" older voices provided by Apple.)

.fxVoiceNames

the list of names of all fxVoices

.allLangs

the list of all short lang name symbols

.allLangNames

the list of all long langName strings

.voicesByLang

return all voices found for the given lang name in optional argVoices (or voices or allVoices). Say.voicesByLang(\en)

.getDefaultVoice

get the current system voice name from macOS defaults (or nil if not set)

.defaultVoiceName

get the system default voice name (cached from last call to .getDefaultVoice)

.findVoice

find voice for given name. When default is true and vocie not found, replace with defaultVoice

.sayVoiceName

say given voice name and its language symbol

.sayVoiceNames

find and say all voice names for a language

.at

return the voice dict at <name>.

.isValidVoice

check whether a symbol is a valid voice name.

.isValidLang

check whether a symbol is a valid language name.

Safety methods

NOTE: The Say program can choke when too many say commands are requested at the same time, making a system restart (or at least user logout/login) necessary. The maxPIDs variable protects against this: additional say commands will be ignored (and posted).

.maxPIDs

get and set the maximum number of say commands that will be processed at the same time. The default value of 10 is quite cautious; on a 2018 MacBook Pro, 32 still works fine. You can tune this for your system,Say.maxPIDs; // default of 10 // slowly rise maxPIDs, run this, wait for it to say the numbers ... Say.maxPIDs = 16; (1..Say.maxPIDs + 5).do (_.say); // did they all finish? Say.pendingPIDs; // maybe you need to kill the pending ones Say.killAll; // now test if say has died: this should still say "alive" "alive?".say; // if this is silent, maxPIDs was set too high, and say is now stuck! // make a note of the highest maxPIDs value that still worked, // and reboot the computer.

.pendingPIDs

the current number of say commands in process, used to check safety.Say.pendingPIDs;

NOTE: The say program handles rate commands a bit clumsily: rates outside the accepted range do not clip at the maximum, but fall back to normal rate! The methods clipRate, minRate, maxRate address this.

.clipRate

get and set flag whether rate values will be clipped.

Say.maxRate

.minRate

.maxRate

get and set current maximum say rates (in syllables per second). Default normal rate for current systems (10.11 .. 10.14) voices is 180, minRate is 90, maxRate is 720.

Examples

// PLEASE SEE TOP EXAMPLES FIRST, then continue here:

// events can wait with next bit of code until first one is finished
// - Note that this blocks the interpreter while speaking!
(
"begin ...".postln;
(type: \say, text: "first sentence ... ", wait: true ).play;
"first one done.".postln;
(type: \say, text: "then second sentence", wait: true).play;
"... and now second one done.".postln;
)

// Within a Routine, you can add wait times, so you can stop the routine
// between spoken sentences
(
fork {
    "begin ...".postln;
    (type: \say, text: "first sentence ... ", wait: true).play;
    "first one done.".postln;
    1.wait;
    (type: \say, text: "then second sentence", wait: true).play;
    "... and now second one done.".postln;
}
)

// Unfortunately the wait option blocks supercollider until say is done,
// so this example could take a while before you can access the interpreter again:
(
Task {
    Say.voices.keep(5).do { |dict, i|
        dict.exampleText.asString.say(i, wait: true);
        // leave holes to stop with cmd-period:
        0.2.wait;
    }
}.play;
)

// You can also use a doneFunc to do something when a say event is finished:
(type: \say, text: "hi there", doneFunc: { "done!".postcs }).play;
// access voices by number, and use wait
(
"hi, this is the first voice in Say.voices speaking".speak(0, true);
// voice 2 and 3 speak in parallel:
"hi, this is the second voice in Say.voices speaking".speak(1, false);
"hi, this is the third voice in Say.voices speaking".speak(2, false);
)

// 'say' has some usage options that can also be scripted from SC.
// In the Terminal, enter 'man say' to read the say manual:
"/Applications/Utilities/Terminal.app".openOS;

// the rate parameter can be given as an event entry:
(type: \say, text: "hi there, i'm talking now", rate: 500).play;
(type: \say, text: "hi there, i'm talking now", rate: 200).play;
(type: \say, text: "hi there, i'm talking now", rate: 100).play;

// or the same can be given as command string called 'cmds', e.g. rate (syllables/min):
(type: \say, text: "hi there, i'm talking now", cmds: "-r 500").play;
(type: \say, text: "hi there, i'm talking now", cmds: "-r 100").play;

// other options include recording to a file:
(
(type: \say, text: "play soundfile via finder", wait: true, cmds: "-o ~/Desktop/text.aiff").play;
// and we used wait: true so the next action happens when done
"~/Desktop/text.aiff".openOS;
unixCmd("afplay" + "~/Desktop/text.aiff");
)

// Say.write is a convenience method to write to a specific folder:
~mydir = Platform.defaultTempDir +/+ "saywrite/";
File.mkdir(~mydir);
~mydir.openOS;
(
Say.write(
    (text: "write to folder saywrite", \lang: \en),
    nil,
    // "test123.aif",
    ~mydir,
    { "file written.".postln }
);
)

// write a list of lines as speech soundfiles
(
~lines = [
    "line 1 is looooong",
    "line 2 not",
    "line 3 ...",
    "line 4 to end."
];

Task {
    var last = ~lines.lastIndex;

~lines.do { |line, i|
        Say.write(
            (text: line, \lang: \en, wait: true),
            (i + 1).asString ++ "_" ++ line ++ ".aif", // use nil for auto filename
            ~mydir,
            {
                ".".post;
                if (i == last) { "\ndone.".postln }
            };
        )
    };
}.play;
)

// For more examples on preparing speech buffers, see:
SayBuf.help

helpfile source: HelpSource/Say.schelp
link::say/Say::

SayExtension