Sound¶

class ev3dev2.sound.Sound¶

Support beep, play wav files, or convert text to speech.

Examples:

from ev3dev2.sound import Sound

spkr = Sound()

# Play 'bark.wav':
spkr.play_file('bark.wav')

# Introduce yourself:
spkr.speak('Hello, I am Robot')

# Play a small song
spkr.play_song((
    ('D4', 'e3'),
    ('D4', 'e3'),
    ('D4', 'e3'),
    ('G4', 'h'),
    ('D5', 'h')
))

In order to mimic EV3-G API parameters, durations used in methods exposed as EV3-G blocks for sound related operations are expressed as a float number of seconds.

PLAY_WAIT_FOR_COMPLETE = 0¶: Play the sound and block until it is complete

PLAY_NO_WAIT_FOR_COMPLETE = 1¶: Start playing the sound but return immediately

PLAY_LOOP = 2¶: Never return; start the sound immediately after it completes, until the program is killed

beep(args='', play_type=0)¶

Call beep command with the provided arguments (if any). See beep man page and google linux beep music for inspiration.

Parameters:	args (string) – Any additional arguments to be passed to `beep` (see the beep man page for details) play_type (`Sound.PLAY_WAIT_FOR_COMPLETE` or `Sound.PLAY_NO_WAIT_FOR_COMPLETE`) – The behavior of `beep` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the spawn subprocess from `subprocess.Popen`; `None` otherwise

tone(*args, play_type=0)¶

tone(tone_sequence)

Play tone sequence.

Here is a cheerful example:

my_sound = Sound()
my_sound.tone([
    (392, 350, 100), (392, 350, 100), (392, 350, 100), (311.1, 250, 100),
    (466.2, 25, 100), (392, 350, 100), (311.1, 250, 100), (466.2, 25, 100),
    (392, 700, 100), (587.32, 350, 100), (587.32, 350, 100),
    (587.32, 350, 100), (622.26, 250, 100), (466.2, 25, 100),
    (369.99, 350, 100), (311.1, 250, 100), (466.2, 25, 100), (392, 700, 100),
    (784, 350, 100), (392, 250, 100), (392, 25, 100), (784, 350, 100),
    (739.98, 250, 100), (698.46, 25, 100), (659.26, 25, 100),
    (622.26, 25, 100), (659.26, 50, 400), (415.3, 25, 200), (554.36, 350, 100),
    (523.25, 250, 100), (493.88, 25, 100), (466.16, 25, 100), (440, 25, 100),
    (466.16, 50, 400), (311.13, 25, 200), (369.99, 350, 100),
    (311.13, 250, 100), (392, 25, 100), (466.16, 350, 100), (392, 250, 100),
    (466.16, 25, 100), (587.32, 700, 100), (784, 350, 100), (392, 250, 100),
    (392, 25, 100), (784, 350, 100), (739.98, 250, 100), (698.46, 25, 100),
    (659.26, 25, 100), (622.26, 25, 100), (659.26, 50, 400), (415.3, 25, 200),
    (554.36, 350, 100), (523.25, 250, 100), (493.88, 25, 100),
    (466.16, 25, 100), (440, 25, 100), (466.16, 50, 400), (311.13, 25, 200),
    (392, 350, 100), (311.13, 250, 100), (466.16, 25, 100),
    (392.00, 300, 150), (311.13, 250, 100), (466.16, 25, 100), (392, 700)
    ])

Have also a look at play_song() for a more musician-friendly way of doing, which uses the conventional notation for notes and durations.

Parameters:

Parameters:	tone_sequence (list[tuple(float,float,float)]) – The sequence of tones to play. The first number of each tuple is frequency in Hz, the second is duration in milliseconds, and the third is delay in milliseconds between this and the next tone in the sequence. play_type (`Sound.PLAY_WAIT_FOR_COMPLETE` or `Sound.PLAY_NO_WAIT_FOR_COMPLETE`) – The behavior of `tone` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the spawn subprocess from `subprocess.Popen`; `None` otherwise

tone_sequence (list[tuple(float,float,float)]) – The sequence of tones to play. The first number of each tuple is frequency in Hz, the second is duration in milliseconds, and the third is delay in milliseconds between this and the next tone in the sequence.
play_type (Sound.PLAY_WAIT_FOR_COMPLETE or Sound.PLAY_NO_WAIT_FOR_COMPLETE) – The behavior of tone once playback has been initiated

Returns:

When python3 is used and Sound.PLAY_NO_WAIT_FOR_COMPLETE is specified, returns the spawn subprocess from subprocess.Popen; None otherwise

tone(frequency, duration)

Play single tone of given frequency and duration.

Parameters:	frequency (float) – The frequency of the tone in Hz duration (float) – The duration of the tone in milliseconds play_type (`Sound.PLAY_WAIT_FOR_COMPLETE` or `Sound.PLAY_NO_WAIT_FOR_COMPLETE`) – The behavior of `tone` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the spawn subprocess from `subprocess.Popen`; `None` otherwise

play_tone(frequency, duration, delay=0.0, volume=100, play_type=0)¶

Play a single tone, specified by its frequency, duration, volume and final delay.

Parameters:	frequency (int) – the tone frequency, in Hertz duration (float) – Tone duration, in seconds delay (float) – Delay after tone, in seconds (can be useful when chaining calls to `play_tone`) volume (int) – The play volume, in percent of maximum volume play_type (`Sound.PLAY_WAIT_FOR_COMPLETE`, `Sound.PLAY_NO_WAIT_FOR_COMPLETE` or `Sound.PLAY_LOOP`) – The behavior of `play_tone` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the PID of the underlying beep command; `None` otherwise
Raises:	ValueError – if invalid parameter

play_note(note, duration, volume=100, play_type=0)¶

Plays a note, given by its name as defined in _NOTE_FREQUENCIES.

Parameters:	note (string) – The note symbol with its octave number duration (float) – Tone duration, in seconds volume (int) – The play volume, in percent of maximum volume play_type (`Sound.PLAY_WAIT_FOR_COMPLETE`, `Sound.PLAY_NO_WAIT_FOR_COMPLETE` or `Sound.PLAY_LOOP`) – The behavior of `play_note` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the PID of the underlying beep command; `None` otherwise
Raises:	ValueError – is invalid parameter (note, duration,…)

play_file(wav_file, volume=100, play_type=0)¶

Play a sound file (wav format) at a given volume. The EV3 audio subsystem will work best if the file is encoded as 16-bit, mono, 22050Hz.

Parameters:	wav_file (string) – The sound file path volume (int) – The play volume, in percent of maximum volume play_type (`Sound.PLAY_WAIT_FOR_COMPLETE`, `Sound.PLAY_NO_WAIT_FOR_COMPLETE` or `Sound.PLAY_LOOP`) – The behavior of `play_file` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the spawn subprocess from `subprocess.Popen`; `None` otherwise

speak(text, espeak_opts='-a 200 -s 130', volume=100, play_type=0)¶

Speak the given text aloud.

Uses the espeak external command.

Parameters:	text (string) – The text to speak espeak_opts (string) – `espeak` command options (advanced usage) volume (int) – The play volume, in percent of maximum volume play_type (`Sound.PLAY_WAIT_FOR_COMPLETE`, `Sound.PLAY_NO_WAIT_FOR_COMPLETE` or `Sound.PLAY_LOOP`) – The behavior of `speak` once playback has been initiated
Returns:	When python3 is used and `Sound.PLAY_NO_WAIT_FOR_COMPLETE` is specified, returns the spawn subprocess from `subprocess.Popen`; `None` otherwise

set_volume(pct, channel=None)¶: Sets the sound volume to the given percentage [0-100] by calling amixer -q set <channel> <pct>%. If the channel is not specified, it tries to determine the default one by running amixer scontrols. If that fails as well, it uses the Playback channel, as that is the only channel on the EV3.

get_volume(channel=None)¶: Gets the current sound volume by parsing the output of amixer get <channel>. If the channel is not specified, it tries to determine the default one by running amixer scontrols. If that fails as well, it uses the Playback channel, as that is the only channel on the EV3.

play_song(song, tempo=120, delay=0.05)¶

Plays a song provided as a list of tuples containing the note name and its value using music conventional notation instead of numerical values for frequency and duration.

It supports symbolic notes (e.g. A4, D#3, Gb5) and durations (e.g. q, h). You can also specify rests by using R instead of note pitch.

For an exhaustive list of accepted note symbols and values, have a look at the _NOTE_FREQUENCIES and _NOTE_VALUES private dictionaries in the source code.

The value can be suffixed by modifiers:

a divider introduced by a / to obtain triplets for instance (e.g. q/3 for a triplet of eight note)
a multiplier introduced by * (e.g. *1.5 is a dotted note).

Shortcuts exist for common modifiers:

3 produces a triplet member note. For instance e3 gives a triplet of eight notes, i.e. 3 eight notes in the duration of a single quarter. You must ensure that 3 triplets notes are defined in sequence to match the count, otherwise the result will not be the expected one.
. produces a dotted note, i.e. which duration is one and a half the base one. Double dots are not currently supported.

Example:

>>> # A long time ago in a galaxy far,
>>> # far away...
>>> from ev3dev2.sound import Sound
>>> spkr = Sound()
>>> spkr.play_song((
>>>     ('D4', 'e3'),      # intro anacrouse
>>>     ('D4', 'e3'),
>>>     ('D4', 'e3'),
>>>     ('G4', 'h'),       # meas 1
>>>     ('D5', 'h'),
>>>     ('C5', 'e3'),      # meas 2
>>>     ('B4', 'e3'),
>>>     ('A4', 'e3'),
>>>     ('G5', 'h'),
>>>     ('D5', 'q'),
>>>     ('C5', 'e3'),      # meas 3
>>>     ('B4', 'e3'),
>>>     ('A4', 'e3'),
>>>     ('G5', 'h'),
>>>     ('D5', 'q'),
>>>     ('C5', 'e3'),      # meas 4
>>>     ('B4', 'e3'),
>>>     ('C5', 'e3'),
>>>     ('A4', 'h.'),
>>> ))

Important

Only 4/4 signature songs are supported with respect to note durations.

Parameters:	song (iterable[tuple(string,string)]) – the song tempo (int) – the song tempo, given in quarters per minute delay (float) – delay between notes (in seconds)
Returns:	When python3 is used the spawn subprocess from `subprocess.Popen` is returned; `None` otherwise
Raises:	ValueError – if invalid note in song or invalid play parameters