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
orSound.PLAY_NO_WAIT_FOR_COMPLETE
) – The behavior ofbeep
once playback has been initiated
Returns: When python3 is used and
Sound.PLAY_NO_WAIT_FOR_COMPLETE
is specified, returns the spawn subprocess fromsubprocess.Popen
;None
otherwise- args (string) – Any additional arguments to be passed to
-
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
orSound.PLAY_NO_WAIT_FOR_COMPLETE
) – The behavior oftone
once playback has been initiated
Returns: When python3 is used and
Sound.PLAY_NO_WAIT_FOR_COMPLETE
is specified, returns the spawn subprocess fromsubprocess.Popen
;None
otherwisetone(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
orSound.PLAY_NO_WAIT_FOR_COMPLETE
) – The behavior oftone
once playback has been initiated
Returns: When python3 is used and
Sound.PLAY_NO_WAIT_FOR_COMPLETE
is specified, returns the spawn subprocess fromsubprocess.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
orSound.PLAY_LOOP
) – The behavior ofplay_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
otherwiseRaises: 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
orSound.PLAY_LOOP
) – The behavior ofplay_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
otherwiseRaises: 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
orSound.PLAY_LOOP
) – The behavior ofplay_file
once playback has been initiated
Returns: When python3 is used and
Sound.PLAY_NO_WAIT_FOR_COMPLETE
is specified, returns the spawn subprocess fromsubprocess.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
orSound.PLAY_LOOP
) – The behavior ofspeak
once playback has been initiated
Returns: When python3 is used and
Sound.PLAY_NO_WAIT_FOR_COMPLETE
is specified, returns the spawn subprocess fromsubprocess.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 runningamixer scontrols
. If that fails as well, it uses thePlayback
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 runningamixer scontrols
. If that fails as well, it uses thePlayback
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 usingR
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 instancee3
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
otherwiseRaises: ValueError – if invalid note in song or invalid play parameters
- a divider introduced by a
-