sound#

class platypush.plugins.sound.PlaybackState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

class platypush.plugins.sound.RecordingState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

class platypush.plugins.sound.SoundPlugin(input_device=None, output_device=None, input_blocksize=1024, output_blocksize=1024, **kwargs)[source]#

Bases: Plugin

Plugin to interact with a sound device.

Triggers:

Requires:

  • sounddevice (pip install sounddevice)

  • soundfile (pip install soundfile)

  • numpy (pip install numpy)

__init__(input_device=None, output_device=None, input_blocksize=1024, output_blocksize=1024, **kwargs)[source]#
Parameters:

  • input_device (int or str) – Index or name of the default input device. Use platypush.plugins.sound.query_devices() to get the available devices. Default: system default

  • output_device (int or str) – Index or name of the default output device. Use platypush.plugins.sound.query_devices() to get the available devices. Default: system default

  • input_blocksize (int) – Blocksize to be applied to the input device. Try to increase this value if you get input overflow errors while recording. Default: 1024

  • output_blocksize (int) – Blocksize to be applied to the output device. Try to increase this value if you get output underflow errors while playing. Default: 1024

pause_playback(streams=None)[source]#
Parameters:

streams (list[int]) – Streams to pause by index (default: all)

play(file=None, sound=None, device=None, blocksize=None, bufsize=None, samplerate=None, channels=None, stream_name=None, stream_index=None)[source]#

Plays a sound file (support formats: wav, raw) or a synthetic sound.

Parameters:

  • file (str) – Sound file path. Specify this if you want to play a file

  • sound – Sound to play. Specify this if you want to play synthetic sounds. You can also create polyphonic sounds by just calling play multiple times.

  • device (int or str) – Output device (default: default configured device or system default audio output if not configured)

  • blocksize (int) – Audio block size (default: configured output_blocksize or 2048)

  • bufsize (int) – Size of the audio buffer (default: 20 frames for audio files, 2 frames for synth sounds)

  • samplerate (int) – Audio samplerate. Default: audio file samplerate if in file mode, 44100 Hz if in synth mode

  • channels (int) – Number of audio channels. Default: number of channels in the audio file in file mode, 1 if in synth mode

  • stream_index (int) – If specified, play to an already active stream index (you can get them through platypush.plugins.sound.query_streams()). Default: creates a new audio stream through PortAudio.

  • stream_name (str) – Name of the stream to play to. If set, the sound will be played to the specified stream name, or a stream with that name will be created. If not set, and stream_index is not set either, then a new stream will be created on the next available index and named platypush-stream-<index>.

query_devices(category=None)[source]#

Query the available devices

Parameters:

category (str) – Device category to query. Can be either input or output. Default: None (query all devices)

Returns:

A dictionary representing the available devices.

Example:

[
    {
        "name": "pulse",
        "hostapi": 0,
        "max_input_channels": 32,
        "max_output_channels": 32,
        "default_low_input_latency": 0.008684807256235827,
        "default_low_output_latency": 0.008684807256235827,
        "default_high_input_latency": 0.034807256235827665,
        "default_high_output_latency": 0.034807256235827665,
        "default_samplerate": 44100
    },
    {
        "name": "default",
        "hostapi": 0,
        "max_input_channels": 32,
        "max_output_channels": 32,
        "default_low_input_latency": 0.008684807256235827,
        "default_low_output_latency": 0.008684807256235827,
        "default_high_input_latency": 0.034807256235827665,
        "default_high_output_latency": 0.034807256235827665,
        "default_samplerate": 44100
    }
]
query_streams()[source]#
Returns:

A list of active audio streams

record(outfile=None, duration=None, device=None, sample_rate=None, format=None, blocksize=None, latency=0, channels=1, subtype='PCM_24')[source]#

Records audio to a sound file (support formats: wav, raw)

Parameters:

  • outfile (str) – Sound file (default: the method will create a temporary file with the recording)

  • duration (float) – Recording duration in seconds (default: record until stop event)

  • device (int or str) – Input device (default: default configured device or system default audio input if not configured)

  • sample_rate (int) – Recording sample rate (default: device default rate)

  • format (str) – Audio format (default: WAV)

  • blocksize (int) – Audio block size (default: configured input_blocksize or 2048)

  • latency (float) – Device latency in seconds (default: 0)

  • channels (int) – Number of channels (default: 1)

  • subtype (str) – Recording subtype - see Soundfile docs - Subtypes for a list of the available subtypes (default: PCM_24)

recordplay(duration=None, input_device=None, output_device=None, sample_rate=None, blocksize=None, latency=0, channels=1, dtype=None)[source]#

Records audio and plays it on an output sound device (audio pass-through)

Parameters:

  • duration (float) – Recording duration in seconds (default: record until stop event)

  • input_device (int or str) – Input device (default: default configured device or system default audio input if not configured)

  • output_device (int or str) – Output device (default: default configured device or system default audio output if not configured)

  • sample_rate (int) – Recording sample rate (default: device default rate)

  • blocksize (int) – Audio block size (default: configured output_blocksize or 2048)

  • latency (float) – Device latency in seconds (default: 0)

  • channels (int) – Number of channels (default: 1)

  • dtype (str) – Data type for the recording - see Soundfile docs - Recording for available types (default: input device default)

release(stream_index=None, stream_name=None, sound_index=None, midi_note=None, frequency=None)[source]#
Remove a sound from an active stream, either by sound index (use

platypush.sound.plugin.SoundPlugin.query_streams() to get the sounds playing on the active streams), midi_note, frequency or absolute file path.

Parameters:

  • stream_index (str) – Stream index (default: sound removed from all the active streams)

  • stream_name – Stream name (default: sound removed from all the active streams)

  • sound_index (int) – Sound index

  • midi_note (int) – MIDI note

  • frequency (float) – Sound frequency

stop_playback(streams=None)[source]#
Parameters:

streams (list[int] or list[str]) – Streams to stop by index or name (default: all)

stream_recording(device=None, fifo=None, duration=None, sample_rate=None, dtype='float32', blocksize=None, latency=0, channels=1)[source]#

Return audio data from an audio source

Parameters:

  • device (int or str) – Input device (default: default configured device or system default audio input if not configured)

  • fifo (str) – Path of the FIFO that will be used to exchange audio samples (default: /tmp/inputstream)

  • duration (float) – Recording duration in seconds (default: record until stop event)

  • sample_rate (int) – Recording sample rate (default: device default rate)

  • dtype (str) – Data type for the audio samples. Supported types: ‘float64’, ‘float32’, ‘int32’, ‘int16’, ‘int8’, ‘uint8’. Default: float32

  • blocksize (int) – Audio block size (default: configured input_blocksize or 2048)

  • latency (float) – Device latency in seconds (default: 0)

  • channels (int) – Number of channels (default: 1)