voicebox.voiceboxes package

Submodules

voicebox.voiceboxes.base module

class voicebox.voiceboxes.base.Voicebox

Bases: ABC

Base class of all voiceboxes.

abstractmethod say(text: str) → None

Say the given text.

say_all(texts: Iterable[str]) → None

Say all the given texts, in order.

async say_all_async(texts: Iterable[str], loop=None, executor=None) → None

Say all the given texts, in order, asynchronously.

async say_async(text: str, loop=None, executor=None) → None

Say the given text asynchronously.

class voicebox.voiceboxes.base.VoiceboxWithTextSplitter(text_splitter: Splitter = None)

Bases: Voicebox

Base class of all voiceboxes that use a text splitter.

say(text: str) → None

Say the given text.

text_splitter: Splitter

voicebox.voiceboxes.parallel module

class voicebox.voiceboxes.parallel.ParallelVoicebox(tts: TTS = None, effects: List[Effect] = None, sink: Sink = None, text_splitter: Splitter = None, start: bool = True, queue_get_timeout: float = 1.0, daemon: bool = True)

Bases: VoiceboxWithTextSplitter

Handles speech on a separate thread so the main thread is not blocked waiting for speech to complete.

Also eliminates loading time between messages by loading the audio for the next message while the current message is playing.

Example

>>> voicebox = ParallelVoicebox(...)
>>> voicebox.say('Hello, world!')   # Does not block; speech handled by thread
>>> voicebox.say('How are you?')    # Does not block
>>> # Do stuff in main thread while speech is happening...
>>> voicebox.wait_until_done()      # Call before program end to prevent cutoff
>>>
>>> # Can be used as context manager
>>> with ParallelVoicebox(...) as voicebox:
>>>     ...
>>> # Voicebox threads are stopped after exiting `with` block

Parameters:

• tts – The voicebox.tts.TTS engine to use.

• effects – Sequence of voicebox.effects.Effect instances to apply to the audio before playing it.

• sink – The voicebox.sinks.Sink to use to play the audio.

• text_splitter – The voicebox.voiceboxes.splitter.Splitter to use to split the text into chunks to be spoken. Defaults to no splitting.

• start – Whether to start the threads.

• queue_get_timeout – Seconds to wait for text to appear in the queue of things to say between checks of the stop flag.

• daemon – Whether the thread is daemonic (i.e. dies when the main thread exits).

property effects: List[Effect]

is_alive() → bool

Return whether the threads are alive.

join(timeout: float = None) → None

Wait until the threads terminate.

Parameters:

timeout – Wait up to this many seconds. None waits forever.

property sink: Sink

start() → None

Start the threads.

stop(wait: bool = False, timeout: float = None) → None

Notify the threads to stop running.

Parameters:

• wait – Whether to wait for the threads to stop.

• timeout – If waiting, then wait up to this many seconds. None waits forever.

property tts: TTS

wait_until_done(timeout: float = None) → None

Wait until all speech is done.

Useful to run before program end to prevent speech from being cut off.

Raises:

NotFinished – If timeout is not None and the timeout is reached before all speech is done.

voicebox.voiceboxes.queue module

exception voicebox.voiceboxes.queue.NotFinished

Bases: Exception

Exception raised by Queue.join() when it times out.

class voicebox.voiceboxes.queue.Queue(maxsize=0)

Bases: Queue

join(timeout: float = None) → None

Blocks until all items in the Queue have been gotten and processed, or until timeout seconds have elapsed.

The count of unfinished tasks goes up whenever an item is added to the queue. The count goes down whenever a consumer thread calls task_done() to indicate the item was retrieved and all work on it is complete.

When the count of unfinished tasks drops to zero, join() unblocks.

Parameters:

timeout – An optional timeout in seconds to wait for unfinished tasks. If None (default), then there is no limit to the wait time.

Raises:

NotFinished – If timeout is not None and the timeout is reached before all tasks are finished.

voicebox.voiceboxes.simple module

class voicebox.voiceboxes.simple.SimpleVoicebox(tts: TTS = None, effects: List[Effect] = None, sink: Sink = None, text_splitter: Splitter = None)

Bases: VoiceboxWithTextSplitter

Uses a TTS engine to convert text to audio, applies a series of effects to the audio, and then plays the audio.

Parameters:

• tts – The voicebox.tts.TTS engine to use.

• effects – Sequence of voicebox.effects.Effect instances to apply to the audio before playing it.

• sink – The voicebox.sinks.Sink to use to play the audio.

• text_splitter – The voicebox.voiceboxes.splitter.Splitter to use to split the text into chunks to be spoken. Defaults to no splitting.

effects: List[Effect]

sink: Sink

tts: TTS

voicebox.voiceboxes.splitter module

class voicebox.voiceboxes.splitter.NltkTokenizerSplitter(tokenizer: TokenizerI)

Bases: Splitter

Uses an NLTK tokenizer to split text.

split(text: str | SSML) → Iterable[str | SSML]

Splits the given text into chunks, unless it is a voicebox.SSML instance, in which case it is returned as-is, i.e. [text].

tokenizer: TokenizerI

class voicebox.voiceboxes.splitter.NoopSplitter

Bases: Splitter

Does not split text.

split(text: str | SSML) → Iterable[str | SSML]

Splits the given text into chunks, unless it is a voicebox.SSML instance, in which case it is returned as-is, i.e. [text].

class voicebox.voiceboxes.splitter.PunktSentenceSplitter(language: str = 'english')

Bases: NltkTokenizerSplitter

Uses the Punkt sentence tokenizer from NLTK to split text into sentences more intelligently than a simple pattern-based splitter. It can handle instances of mid-sentence punctuation very well; e.g. “Mr. Jones went to see Dr. Sherman” would be correctly “split” into only one sentence.

This requires that the Punkt NLTK resources be located on disk, e.g. by downloading via one of these methods:

>>> PunktSentenceSplitter.download_resources()

or

>>> import nltk; nltk.download('punkt_tab')

or

$ python -m nltk.downloader punkt_tab

See here for all NLTK Data installation methods: https://www.nltk.org/data.html

static download_resources(**kwargs)

Download the Punkt NLTK resources.

class voicebox.voiceboxes.splitter.RegexSplitter(pattern: str | Pattern, join_split_group: bool = True)

Bases: Splitter

Splits text on regex pattern.

join_split_group: bool

pattern: Pattern

split(text: str | SSML) → Iterable[str | SSML]

Splits the given text into chunks, unless it is a voicebox.SSML instance, in which case it is returned as-is, i.e. [text].

class voicebox.voiceboxes.splitter.SimpleSentenceSplitter

Bases: RegexSplitter

Splits text on sentence punctuation ‘.’, ‘!’, and ‘?’.

class voicebox.voiceboxes.splitter.Splitter

Bases: ABC

Splits text into chunks.

abstractmethod split(text: str | SSML) → Iterable[str | SSML]

Splits the given text into chunks, unless it is a voicebox.SSML instance, in which case it is returned as-is, i.e. [text].

voicebox.voiceboxes.splitter.default_splitter() → Splitter

Module contents