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:
  • 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