/usr/share/doc/python-sfml-doc/html/_sources/api/audio.txt is in python-sfml-doc 1.5.1.is.1.3+dfsg-1build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 | 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 instanciated.
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 orientation of the listener in the scene.
The orientation defines the 3D axes of the listener (left, up,
front) in the scene. The orientation vector doesn't have to be
normalized. The default listener's orientation is (0, 0, -1).
:param direction: New listener's orientation
:type direction: :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 opartor
**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: an :class:`sfml.audio.SoundSource`'s contant
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: an :class:`sfml.audio.SoundSource`'s contant
.. 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 overriden 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 overriden 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 additionnal method can be overriden 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.
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` and :func:`on_stop` methods
(but not :func:`on_start`) 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.
:param integer sample_rate: Desired capture rate, in number of samples per second
.. 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:: 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 overriden 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 overriden 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`
|