Audio ===== .. module:: sfml.audio .. contents:: :local: Listener ^^^^^^^^ .. class:: Listener The audio listener is the point in the scene from where all the sounds are heard. The audio listener defines the global properties of the audio environment, it defines where and how sounds and musics are heard. If :class:`.View` is the eyes of the user, then :class:`Listener` is his ears (by the way, they are often linked together -- same position, orientation, etc.). :class:`Listener` is a simple interface, which allows to setup the listener in the 3D audio environment (position and direction), and to adjust the global volume. Because the listener is unique in the scene, :class:`Listener` only contains class methods and doesn't have to be instantiated. Usage example:: # move the listener to the position (1, 0, -5) sf.Listener.set_position(sfml.system.Vector3(1, 0, -5)) # make it face the right axis (1, 0, 0) sf.Listener.set_direction(sfml.system.Vector3(1, 0, 0)) # reduce the global volume sf.Listener.set_global_volume = 50 .. classmethod:: get_global_volume() Get the current value of the global volume. :return: Current global volume, in the range [0, 100] :rtype: float .. classmethod:: set_global_volume(volume) Change the global volume of all the sounds and musics. The volume is a number between 0 and 100; it is combined with the individual volume of each sound / music. The default value for the volume is 100 (maximum). :param float volume: New global volume, in the range [0, 100] .. classmethod:: get_position() Get the current position of the listener in the scene. :return: Listener's position :rtype: :class:`sfml.system.Vector3` .. classmethod:: set_position(position) Set the position of the listener in the scene. The default listener's position is (0, 0, 0). :param position: New listener's position :type position: :class:`sfml.system.Vector3` or tuple .. classmethod:: get_direction() Get the current orientation of the listener in the scene. :return: Listener's orientation :rtype: :class:`sfml.system.Vector3` .. classmethod:: set_direction(direction) Set the forward vector of the listener in the scene. The direction (also called "at vector") is the vector pointing forward from the listener's perspective. Together with the up vector, it defines the 3D orientation of the listener in the scene. The direction vector doesn't have to be normalized. The default listener's direction is (0, 0, -1). :param direction: New listener's forward vector (not normalized) :type direction: :class:`sfml.system.Vector3` or tuple .. classmethod:: get_up_vector() Get the current upward vector of the listener in the scene. :return: Listener's upward vector (not normalized) :rtype: :class:`sfml.system.Vector3` .. classmethod:: set_up_vector(up_vector) Set the upward vector of the listener in the scene. The up vector is the vector that points upward from the listener's perspective. Together with the direction, it defines the 3D orientation of the listener in the scene. The up vector doesn't have to be normalized. The default listener's up vector is (0, 1, 0). It is usually not necessary to change it, especially in 2D scenarios. :param up_vector: New listener's up vector :type up_vector: :class:`sfml.system.Vector3` or tuple Chunk ^^^^^ .. class:: Chunk :class:`Chunk` represents internally an array of **Int16** which are sound samples. It provides utilities to manipulate such an array in Python and a property :attr:`data` to access the underlying data representation. .. py:method:: __len__() Return the number of sample. .. py:method:: __getitem__(index) Get an access to a sample by its index. .. py:method:: __setitem__(index, vertex) Set a sample value by its index. .. py:attribute:: data Get a **copy** of the data inside. This returns a byte array twice larger than the chunck's lenght. Set a new array of sample. This array is an array of bytes (which will be converted internally in an array of **Int16**) and its lenght must be an even number. :rtype: bytes or string SoundBuffer ^^^^^^^^^^^ .. class:: SoundBuffer Storage for audio samples defining a sound. A sound buffer holds the data of a sound, which is an array of audio samples. A sample is a 16 bits signed integer that defines the amplitude of the sound at a given time. The sound is then restituted by playing these samples at a high rate (for example, 44100 samples per second is the standard rate used for playing CDs). In short, audio samples are like texture pixels, and an :class:`SoundBuffer` is similar to an :class:`.Texture`. A sound buffer can be loaded from a file (see :func:`from_file()` for the complete list of supported formats), from memory or directly from an array of samples. It can also be saved back to a file. Sound buffers alone are not very useful: they hold the audio data but cannot be played. To do so, you need to use the :class:`Sound` class, which provides functions to play/pause/stop the sound as well as changing the way it is outputted (volume, pitch, 3D position, ...). This separation allows more flexibility and better performances: indeed a :class:`SoundBuffer` is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, an :class:`Sound` is a lightweight object, which can use the audio data of a sound buffer and change the way it is played without actually modifying that data. Note that it is also possible to bind several :class:`Sound` instances to the same :class:`SoundBuffer`. It is important to note that the :class:`Sound` instance doesn't copy the buffer that it uses, it only keeps a reference to it. Thus, an :class:`SoundBuffer` must not be destructed while it is used by an :class:`Sound` (i.e. never write a function that uses a local :class:`SoundBuffer` instance for loading a sound). Usage example:: # load a new sound buffer from a file try: buffer = sf.SoundBuffer.from_file("data/sound.wav") except IOError as error: exit() # create a sound source and bind it to the buffer sound1 = sf.Sound() sound1.buffer = buffer # play the sound sound1.play(); input() # create another sound source bound to the same buffer sound2 = sf.Sound(buffer) # play it with higher pitch -- the first sound remains unchanged sound2.pitch = 2 sound2.play() .. method:: SoundBuffer([buffer]) If you try to instantiate an :class:`SoundBuffer` directly, it will raise an error saying that you have to use its specific constructors: `from_file`, `from_memory` or `from_samples` .. py:classmethod:: from_file(filename) Load the sound buffer from a file. Here is a complete list of all the supported audio formats: **ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64**. :raise: :exc:`IOError` - The SoundBuffer failed to load :param str filename: Path of the sound file to load :rtype: :class:`sfml.audio.SoundBuffer` .. classmethod:: from_memory(data) Load the sound buffer from a file in memory. Here is a complete list of all the supported audio formats: ogg, wav, **flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64**. :raise: :exc:`IOError` - The SoundBuffer failed to load :param bytes data: The file data :rtype: :class:`sfml.audio.SoundBuffer` .. classmethod:: from_samples(samples, channel_count, sample_rate) Load the sound buffer from an array of audio samples. :raise: :exc:`IOError` - The SoundBuffer failed to load :param sfml.audio.Chunk samples: The samples :param integer channel_count: Number of channels (1 = mono, 2 = stereo, ...) :param integer sample_rate: Sample rate (number of samples to play per second) :rtype: :class:`sfml.audio.SoundBuffer` .. method:: to_file(filename) Save the sound buffer to an audio file. Here is a complete list of all the supported audio formats: **ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64**. :raise: :exc:`IOError` - The SoundBuffer failed to save :param str filename: Path of the sound file to write .. attribute:: channels_count Get the number of channels used by the sound. If the sound is mono then the number of channels will be 1, 2 for stereo, etc. :rtype: integer .. attribute:: duration Get the total duration of the sound. :rtype: :class:`sfml.system.Time` .. attribute:: sample_rate Get the sample rate of the sound. The sample rate is the number of samples played per second. The higher, the better the quality (for example, 44100 samples/s is CD quality). :rtype: integer .. attribute:: samples Get the audio samples stored in the buffer. :rtype: :class:`sfml.audio.Chunk` SoundSource ^^^^^^^^^^^ .. class:: SoundSource Base class defining a sound's properties. :class:`SoundSource` is not meant to be used directly, it only serves as a common base for all audio objects that can live in the audio environment. It defines several properties for the sound: pitch, volume, position, attenuation, etc. All of them can be changed at any time with no impact on performances. .. py:data:: STOPPED Sound is not playing. .. py:data:: PAUSED Sound is paused. .. py:data:: PLAYING Sound is playing. .. attribute:: pitch Get/set the pitch of the sound. The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave by changing its pitch. A side effect of changing the pitch is to modify the playing speed of the sound as well. The default value for the pitch is 1. :rtype: float .. attribute:: volume Get/set the volume of the sound. The volume is a value between 0 (mute) and 100 (full volume). The default value for the volume is 100. :rtype: float .. attribute:: position Get/set the 3D position of the sound in the audio scene. Only sounds with one channel (mono sounds) can be spatialized. The default position of a sound is (0, 0, 0). :rtype: :class:`sfml.system.Vector3` .. attribute:: relative_to_listener Make the sound's position relative to the listener or absolute. Making a sound relative to the listener will ensure that it will always be played the same way regardless the position of the listener. This can be useful for non-spatialized sounds, sounds that are produced by the listener, or sounds attached to it. The default value is false (position is absolute). :rtype: bool .. attribute:: min_distance The minimum distance of the sound. The "minimum distance" of a sound is the maximum distance at which it is heard at its maximum volume. Further than the minimum distance, it will start to fade out according to its attenuation factor. A value of 0 ("inside the head of the listener") is an invalid value and is forbidden. The default value of the minimum distance is 1. .. attribute:: attenuation Get/set the attenuation factor of the sound. The attenuation is a multiplicative factor which makes the sound more or less loud according to its distance from the listener. An attenuation of 0 will produce a non-attenuated sound, i.e. its volume will always be the same whether it is heard from near or from far. On the other hand, an attenuation value such as 100 will make the sound fade out very quickly as it gets further from the listener. The default value of the attenuation is 1. :rtype: float Sound ^^^^^ .. class:: Sound(SoundSource) Regular sound that can be played in the audio environment. :class:`Sound` is the class to use to play sounds. It provides: * Control (play, pause, stop) * Ability to modify output parameters in real-time (pitch, volume, ...) * 3D spatial features (position, attenuation, ...). :class:`Sound` is perfect for playing short sounds that can fit in memory and require no latency, like foot steps or gun shots. For longer sounds, like background musics or long speeches, rather see :class:`Music` (which is based on streaming). In order to work, a sound must be given a buffer of audio data to play. Audio data (samples) is stored in :class:`SoundBuffer`, and attached to a sound with the :func:`SoundBuffer.buffer` function. The buffer object attached to a sound must remain alive as long as the sound uses it, so don't delete it explicitly with the operator **del**. Note that multiple sounds can use the same sound buffer at the same time. Usage example:: try: buffer = sf.SoundBuffer.from_file("sound.wav") except IOError: exit(1) sound = sf.Sound() sound.buffer = buffer sound.play() .. method:: Sound([buffer]) Construct the sound with a buffer or if not provided construct an empty sound. :param sfml.audio.SoundBuffer buffer: Sound buffer containing the audio data to play with the sound .. method:: play() Start or resume playing the sound. This function starts the stream if it was stopped, resumes it if it was paused, and restarts it from beginning if it was it already playing. This function uses its own thread so that it doesn't block the rest of the program while the sound is played. .. method:: pause() Pause the sound. This function pauses the sound if it was playing, otherwise (sound already paused or stopped) it has no effect. .. method:: stop() Stop playing the sound. This function stops the sound if it was playing or paused, and does nothing if it was already stopped. It also resets the playing position (unlike :func:`pause`). .. attribute:: buffer Get/set the source buffer containing the audio data to play. It is important to note that the sound buffer is not copied, thus the :class:`SoundBuffer` instance must remain alive as long as it is attached to the sound (don't explicitly delete it with the operator **del**). :rtype: :class:`sfml.audio.SoundBuffer` .. attribute:: loop Set/tell whether or not the sound should loop after reaching the end. If set, the sound will restart from beginning after reaching the end and so on, until it is stopped or `loop` is set at false again. The default looping state for sound is false. :rtype: bool .. attribute:: playing_offset Change the current playing position of the sound. The playing position can be changed when the sound is either paused or playing. :rtype: :class:`sfml.system.Time` .. attribute:: status Get the current status of the sound (stopped, paused, playing) :rtype: a constant from :class:`sfml.audio.SoundSource` SoundStream ^^^^^^^^^^^ .. class:: SoundStream(SoundSource) Abstract base class for streamed audio sources. Unlike audio buffers (see :class:`SoundBuffer`), audio streams are never completely loaded in memory. Instead, the audio data is acquired continuously while the stream is playing. This behaviour allows to play a sound with no loading delay, and keeps the memory consumption very low. Sound sources that need to be streamed are usually big files (compressed audio musics that would eat hundreds of MB in memory) or files that would take a lot of time to be received (sounds played over the network). :class:`SoundStream` is a base class that doesn't care about the stream source, which is left to the derived class. pySFML provides a built-in specialization for big files (see :class:`Music`). No network stream source is provided, but you can write your own by combining this class with the network module. A derived class has to override two virtual functions: - :meth:`on_get_data` fills a new chunk of audio data to be played - :meth:`on_seek` changes the current playing position in the source It is important to note that each :class:`SoundStream` is played in its own separate thread, so that the streaming loop doesn't block the rest of the program. In particular, the :func:`on_get_data` and :func:`on_seek` virtual functions may sometimes be called from this separate thread. It is important to keep this in mind, because you may have to take care of synchronization issues if you share data between threads. Usage example:: class CustomStream(sf.SoundStream): def __init__(self): sf.SoundStream.__init__(self) # don't forget this def open(location): # open the source and get audio settings ... channel_count = ... sample_rate = ... # initialize the stream -- important! self.initialize(channel_count, sample_rate) def on_get_data(self, data): # fill the chunk with audio data from the stream source data += another_chunk # return true to continue playing return True def on_seek(self, time_offset): # change the current position in the stream source ... # usage stream = CustomStream() stream.open("path/to/stream") stream.play() .. method:: play() Start or resume playing the audio stream. This function starts the stream if it was stopped, resumes it if it was paused, and restarts it from beginning if it was it already playing. This function uses its own thread so that it doesn't block the rest of the program while the stream is played. .. method:: pause() Pause the audio stream. This function pauses the stream if it was playing, otherwise (stream already paused or stopped) it has no effect. .. method:: stop() Stop playing the audio stream. This function stops the stream if it was playing or paused, and does nothing if it was already stopped. It also resets the playing position (unlike :func:`pause`). .. attribute:: channel_count Return the number of channels of the stream. 1 channel means a mono sound, 2 means stereo, etc. :rtype: integer .. attribute:: sample_rate Get the stream sample rate of the stream. The sample rate is the number of audio samples played per second. The higher, the better the quality. :rtype: integer .. attribute:: loop Set/tell whether or not the stream should loop after reaching the end. If set, the stream will restart from beginning after reaching the end and so on, until it is stopped or :attr:`loop` is set at false again. The default looping state for streams is false. :rtype: bool .. attribute:: playing_offset Change the current playing position of the stream. The playing position can be changed when the stream is either paused or playing. :rtype: :class:`sfml.system.Time` .. attribute:: status Get the current status of the stream (stopped, paused, playing) :rtype: a constant from :class:`sfml.audio.SoundSource` .. method:: initialize(channel_count, sample_rate) Define the audio stream parameters. This function must be called by derived classes as soon as they know the audio settings of the stream to play. Any attempt to manipulate the stream (:func:`play`, ...) before calling this function will fail. It can be called multiple times if the settings of the audio stream change, but only when the stream is stopped. :param integer channel_count: Number of channels of the stream :param integer sample_rate: Sample rate, in samples per second .. method:: on_get_data(data) Request a new chunk of audio samples from the stream source. This function must be overridden by derived classes to provide the audio samples to play. It is called continuously by the streaming loop, in a separate thread. The source can choose to stop the streaming loop at any time, by returning false to the caller. :param sfml.audio.Chunk data: Chunk data to fill :return: True to continue playback, false to stop .. method:: on_seek(time_offset) Change the current playing position in the stream source. This function must be overridden by derived classes to allow random seeking into the stream source. :param sfml.system.Time time_offset: New playing position, relative to the beginning of the stream Music ^^^^^ .. class:: Music(SoundStream) Streamed music played from an audio file. Musics are sounds that are streamed rather than completely loaded in memory. This is especially useful for compressed musics that usually take hundreds of MB when they are uncompressed: by streaming it instead of loading it entirely, you avoid saturating the memory and have almost no loading delay. Apart from that, an :class:`Music` has almost the same features as the :class:`SoundBuffer` / :class:`Sound` pair: you can play/pause/stop it, request its parameters (channels, sample rate), change the way it is played (pitch, volume, 3D position, ...), etc. As a sound stream, a music is played in its own thread in order not to block the rest of the program. This means that you can leave the music alone after calling :meth:`~SoundStream.play`, it will manage itself very well. Usage example:: # declare a new music music = sf.Music() try: music = sf.Music.from_file("music.ogg") except IOError: exit(1) # change some parameters music.position = (0, 1, 10) # change its 3D position music.pitch = 2 # increase the pitch music.volume = 50 # reduce the volume music.loop = True # make it loop # play it music.play() .. method:: Music() If you try to instantiate an :class:`Music` directly, it will raise an error saying that you must use its specific constructors: :meth:`from_file` or :meth:`from_memory`. .. classmethod:: from_file(filename) Open a music from an audio file. This function doesn't start playing the music (call :func:`play` to do so). Here is a complete list of all the supported audio formats: **ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64**. :raise: :exc:`IOError` - If loading failed. :param str filename: Path of the music file to open :rtype: :class:`sfml.audio.Music` .. classmethod:: from_memory(data) Open a music from an audio file in memory. This function doesn't start playing the music (call :func:`play` to do so). Here is a complete list of all the supported audio formats: **ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64**. :raise: :exc:`IOError` - If loading failed. :param bytes data: The file data in memory :rtype: :class:`sfml.audio.Music` .. attribute:: duration Get the total duration of the music :rtype: :class:`sfml.system.Time` SoundRecorder ^^^^^^^^^^^^^ .. class:: SoundRecorder Abstract base class for capturing sound data. :class:`SoundBuffer` provides a simple interface to access the audio recording capabilities of the computer (the microphone). As an abstract base class, it only cares about capturing sound samples, the task of making something useful with them is left to the derived class. Note that pySFML provides a built-in specialization for saving the captured data to a sound buffer (see :class:`SoundBufferRecorder`). A derived class has only one method to override: - :func:`on_process_samples` provides the new chunks of audio samples while the capture happens Moreover, two additional method can be overridden as well if necessary: - :func:`on_start` is called before the capture happens, to perform custom initializations - :func:`on_stop` is called after the capture ends, to perform custom cleanup The audio capture feature may not be supported or activated on every platform, thus it is recommended to check its availability with the :func:`is_available` function. If it returns false, then any attempt to use an audio recorder will fail. If you have multiple sound input devices connected to your computer (for example: microphone, external soundcard, webcam mic, ...), you can get a list of all available devices throught then :meth:`get_available_devices` function. You can then select a device by calling :meth:`set_device` with the appropiate device. Otherwise the default capturing device will be used. It is important to note that the audio capture happens in a separate thread, so that it doesn't block the rest of the program. In particular, the :func:`on_process_samples` method (but not :func:`on_start` and not :func:`on_stop`) will be called from this separate thread. It is important to keep this in mind, because you may have to take care of synchronization issues if you share data between threads. Usage example:: class CustomRecorder(sf.SoundRecorder): def __init__(self): sf.SoundRecorder.__init__(self) def on_start(self): # optional # initialize whatever has to be done before the capture starts ... # return true to start playing return True def on_process_samples(self, samples): # do something with the new chunk of samples (store them, send them, ...) ... # return true to continue playing return True def on_stop(): # optional # clean up whatever has to be done after the capture ends ... # usage if CustomRecorder.is_available(): recorder = CustomRecorder() recorder.start() ... recorder.stop() .. method:: start([sample_rate=44100]) Start the capture. The *sample_rate* parameter defines the number of audio samples captured per second. The higher, the better the quality (for example, 44100 samples/sec is CD quality). This function uses its own thread so that it doesn't block the rest of the program while the capture runs. Please note that only one capture can happen at the same time. You can select which capture device will be used, by passing the name to the :meth:`set_device` method. If none was selected before, the default capture device will be used. You can get a list of the names of all available capture devices by calling :meth:`get_available_devices`. You can select which capture device will be used, by passing the name to the :meth:`set_device` method. If none was selected before, the default capture device will be used. You can get a list of the names of all available capture devices by calling :meth:`get_available_devices`. :param integer sample_rate: Desired capture rate, in number of samples per second :return: True, if start of capture was successful :rtype: boolean .. method:: stop() Stop the capture. .. attribute:: sample_rate Get the sample rate. The sample rate defines the number of audio samples captured per second. The higher, the better the quality (for example, 44100 samples/sec is CD quality). .. classmethod:: get_available_devices() Get a list of the names of all availabe audio capture devices. This function returns a tuple of strings, containing the names of all availabe audio capture devices. :return: A tuple of strings containing the names :rtype: tuple .. classmethod:: get_default_device() Get the name of the default audio capture device. This function returns the name of the default audio capture device. If none is available, None is returned. :return: The name of the default audio capture device :rtype: string (or None) .. method:: set_device(name) Set the audio capture device. This function sets the audio capture device to the device with the given name. It can be called on the fly (i.e: while recording). If you do so while recording and opening the device fails, it stops the recording. :param str name: The name of the audio capture device :return: True, if it was able to set the requested device :rtype: boolean .. method:: get_device() Get the name of the current audio capture device. :return: The name of the current audio capture device :rtype: str .. classmethod:: is_available() Check if the system supports audio capture. This function should always be called before using the audio capture features. If it returns false, then any attempt to use :class:`SoundRecorder` or one of its derived classes will fail. :return: Whether audio capture is supported or not :rtype: bool .. method:: on_start() Start capturing audio data. This method may be overridden by a derived class if something has to be done every time a new capture starts. If not, this method can be ignored; the default implementation does nothing. :return: True to start the capture, or false to abort it .. method:: on_process_samples(samples) Process a new chunk of recorded samples. This method is called every time a new chunk of recorded data is available. The derived class can then do whatever it wants with it (storing it, playing it, sending it over the network, etc.). :param sfml.audio.Chunk samples: The new chunk of recorded samples :return: True to continue the capture, or false to stop it .. method:: on_stop() Stop capturing audio data. This method may be overridden by a derived class if something has to be done every time the capture ends. If not, this method can be ignored; the default implementation does nothing. SoundBufferRecorder ^^^^^^^^^^^^^^^^^^^ .. class:: SoundBufferRecorder(SoundRecorder) Specialized :class:`SoundRecorder` which stores the captured audio data into a sound buffer. :class:`SoundBufferRecorder` allows to access a recorded sound through an :class:`SoundBuffer`, so that it can be played, saved to a file, etc. It has the same simple interface as its base class (:meth:`start`, :meth:`stop`) and adds a property to retrieve the recorded sound buffer (:attr:`buffer`). As usual, don't forget to call the :func:`is_available` function before using this class (see :class:`SoundRecorder` for more details about this). Usage example:: if sf.SoundBufferRecorder.is_available(): # record some audio data recorder = sf.SoundBufferRecorder() recorder.start() ... recorder.stop() # get the buffer containing the captured audio data buffer = recorder.buffer # save it to a file (for example...) buffer.to_file("my_record.ogg") .. method:: SoundBufferRecorder() Construct a :class:`SoundBufferRecorder`. .. attribute:: buffer Get the sound buffer containing the captured audio data. The sound buffer is valid only after the capture has ended. This attribute provides a read-only access to the internal sound buffer, but it can be copied if you need to make any modification to it. :rtype: :class:`sfml.audio.SoundBuffer`