Sound

Introduction

The VEX AIR Drone Controller allows users to play built-in sounds, custom audio files, and musical notes. It also includes controls for stopping sounds and detecting if audio is currently playing.

Below is a list of all available methods:

Actions - Play and Stop Sounds

• play – Plays a built-in sound from a predefined list.

• play_file – Plays a user-uploaded sound.

• play_note – Plays a musical note with a specified pitch, octave, and duration.

• stop – Stops any currently playing sound. Getters - Get Status of Sounds

• is_active – Checks if a sound is currently playing.

Actions

play

play plays one of the controller’s built-in sounds at a specified volume percentage. Since this is a non-waiting method, the controller plays the built-in sound and moves to the next command without waiting for it to finish.

Usage:

controller.sound.play(sound, volume)

Parameter	Description
sound	One of the built-in sound options listed below.
volume	Optional. The volume for the sound, as an integer from 0 to 100 percent. The default is 50 percent.

Built-In Sounds	Play Sound
SUCCESS	Play
FAULT	Play
SENSING	Play
DETECTED	Play
OBSTACLE	Play
LOOPING	Play
COMPLETE	Play
PAUSE	Play
RESUME	Play
SEND	Play
RECEIVE	Play

# Play the looping sound.
controller.sound.play(LOOPING)

# Play the looping sound at full volume.
controller.sound.play(LOOPING, 100)

# Play the looping sound. 
# Wait until the sound is finished before taking off.
controller.sound.play(LOOPING)
while controller.sound.is_active():
    wait(50, MSEC)
drone.take_off(starting_altitude=500)
wait(1, SECONDS)
drone.land()

play_file

play_file plays a custom sound loaded by the user at a specified volume percentage. Since this is a non-waiting method, the drone plays the custom sound and moves to the next command without waiting for it to finish.

Usage:

controller.sound.play_file(sound_name, volume)

Parameter	Description
sound_name	One of the custom sound files uploaded by the user, from SOUND1 to SOUND10. The sound number aligns with the number shown in the AIR Control Panel.
volume	Optional. The volume for the sound, as an integer from 0 to 100 percent. The default is 50 percent.

# Upload a sound file in VEXcode.
# Play the custom sound.
controller.sound.play_file(SOUND1)

# Upload a sound file in VEXcode.
# Play the custom sound at full volume.
controller.sound.play_file(SOUND1, 100)

# Play the custom sound sound. 
# Wait until the sound is finished before taking off.
controller.sound.play_file(SOUND1)
while controller.sound.is_active():
    wait(50, MSEC)
drone.take_off(starting_altitude=500)
wait(1, SECONDS)
drone.land()

play_note

play_note plays a specific note for a specific duration. Since this is a non-waiting method, the drone plays the specific note and moves to the next command without waiting for it to finish.

Usage:

controller.sound.play_note(note, duration, volume)

Parameters	Description
note	Defines the musical pitch: C5, C#5, D5, D#5, E5, F5, F#5, G5, G#5, A5, A#5, B5, C6, C#6, D6, D#6, E6, F6, F#6, G6, G#6, A6, A#6 and B6 as a string.
duration	Sets the length of the note as an integer in milliseconds (ms).
volume	Optional. The volume of the specified sound as an integer percentage from 0 to 100. The default is 50 percent.

Parameter	Description
note	The musical pitch to play, written as a string (e.g., C5, A#6). Valid notes are A through G (with optional # for sharps) across octaves 5 to 8.
duration	The duration of the note, given as an integer in milliseconds.
volume	Optional. The volume of the note, as an integer from 0 to 100 percent. The default is 50 percent.

# Play C5 for 2 seconds
controller.sound.play_note("C5", 2000)

# Play C5 for 2 seconds at full volume
controller.sound.play_note("C5", 2000, 100)

# Play a short tune.
controller.sound.play_note("C5", 1000)
while controller.sound.is_active():
    wait(50, MSEC)
controller.sound.play_note("D5", 1000)
while controller.sound.is_active():
    wait(50, MSEC)
controller.sound.play_note("E5", 250)
while controller.sound.is_active():
    wait(50, MSEC)

stop

stop stops a sound that is currently playing.

Usage:

controller.sound.stop()

Parameters	Description
	This method has no parameters.

# Upload a sound 10 seconds or greater in VEXcode.
# Stop the sound while it is playing.
controller.sound.play_file(SOUND1)
wait(6, SECONDS)
controller.sound.stop()

Getters

is_active

is_active returns whether the drone is currently playing a sound as a Boolean.

• True – A sound is currently playing

• False – No sound is playing

Usage:

controller.sound.is_active()

Parameters	Description
	This method has no parameters.

# Display text when the sound is playing.
controller.sound.play(LOOPING)
while not controller.sound.is_active():
    wait(50, MSEC)
print("I hear the sound!")