Source

pygame / doc / src / sdlmixerbase.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.sdlmixer.base">
  <show>0</show>
  <alias>pygame2.sdlmixer</alias>
  <short>basic SDL_mixer wrapper module</short>
  <desc>
    .. note::
      
      Do not use :mod:`pygame2.sdlmixer` and :mod:`pygame2.sdl.audio` at the
      same time. As they both deal with audio hardware access, this can lead
      to problems and weird behaviour.
  
  </desc>

  <class name="Channel">
    <constructor>Channel ([index]) -> Channel</constructor>
    <desc>Creates a new Channel for playing audio data
    
      Channel represents a playback destination for audio data.
      SDL_mixer can handle multiple channels to play audio simultanously.

      If *index* is omitted or smaller than 1, a new Channel will be created.
      Otherwise Channel will refer to an existing channel and reuse it.
      
      .. note::
         
         The state of an existing channel will not be reset.
    </desc>
    <attr name="chunk">
      <desc>The current :class:`Chunk` of audio data to be played.</desc>
    </attr>
    <method name="expire">
      <call>expire (ms) -> None</call>
      <desc>Halts the playback of the Channel after *ms* milliseconds.</desc>
    </method>
    <method name="fade_in">
      <call>fade_in (sound, ms[, loops, ticks]) -> None</call>
      <desc>Fades in the passed sound.
      
        This starts playing the passed *sound* at volume 0, which fades up to
        the maximum value over *ms* milliseconds. The *sound* will be played
        for *loops* + 1 number of times.
        
        *ticks* is the optional maximum time in milliseconds to stop playing
        after.
      </desc>
    </method>
    <method name="fade_out">
      <call>fade_out (ms) -> None</call>
      <desc>Fades out the current audio playback.
      
      This gradually reduces the volume to 0 over *ms* milliseconds. The channel
      will be halted after the fadeout is complete.
      </desc>
    </method>
    <attr name="fading">
      <desc>The fading status of the Channel.</desc>
    </attr>
    <method name="halt">
      <call>halt () -> None</call>
      <desc>Stops the audio playback immediately and resets the playback state
      </desc>
    </method>
    <method name="pause">
      <call>pause () -> None</call>
      <desc>Pauses the current audio playback.</desc>
    </method>
    <attr name="paused">
      <desc>Gets, whether the Channel playback is currently paused.</desc>
    </attr>
    <method name="play">
      <call>play (sound[, loops, ticks]) -> None</call>
      <desc>Starts the playback of an audio :class:`Chunk`.
      
        The audio chunk will be played for *loops* + 1 times (or one time only, 
        if *loops* is omitted).
        
        *ticks* is the optional maximum time in milliseconds to stop playing
        after.
      </desc>
    </method>
    <attr name="playing">
      <desc>Gets, whether the Channel is currently playing audio.</desc>
    </attr>
    <method name="resume">
      <call>resume () -> None</call>
      <desc>Resumes the playback of a paused sound chunk.</desc>
    </method>
    <attr name="volume">
      <desc>Gets or sets the channel volume.</desc>
    </attr>
  </class>

  <class name="Chunk">
    <constructor>Chunk (file) -> Chunk</constructor>
    <desc>Creates a new sound chunk for audio playback.
    
      .. note::

        The file object *must* support binary read and write
        access. This is especially important for Python 3.x users.
    </desc>
    <attr name="buf">
      <desc>Gets the raw audio buffer of the Chunk.</desc>
    </attr>
    <attr name="len">
      <desc>Gets the length of the audio data.</desc>
    </attr>
    <attr name="volume">
      <desc>Gets or sets the default volume for the audio data.</desc>
    </attr>
  </class>

  <class name="Music">
    <constructor>Music (file) -> Music</constructor>
    <desc>Creates a new sound chunk for music playback.

      .. note::

        The file object *must* support binary read and write
        access. This is especially important for Python 3.x users.
    </desc>
    <method name="fade_in">
      <call>fade_in (ms[, loops, pos]) -> None</call>
      <desc>Fades in the Music.
      
        This starts playing the Music at volume 0, which fades up to
        the maximum value over *ms* milliseconds. The Music will be played
        for *loops* + 1 number of times.
        
        *pos* is the position to start the playback from.
      </desc>
    </method>
    <method name="play">
      <call>play ([loops]) -> None</call>
      <desc>Starts the playback of the Music.
      
        Starts the playback of the Music. The music will be played once, if
        *loops* is omitted, otherwise it will be played *loops* + 1 times.
      </desc>
    </method>
    <attr name="type">
      <desc>Gets the music format.</desc>
    </attr>
  </class>

  <func name="close_audio">
    <call>close_audio () -> None</call>
    <desc>
      Closes an opened instance of the audio hardware.

      Use :func:`query_spec` to detect how often :func:`close_audio` has
      to be called.

      After calling this function (often enough), you should not invoke
      any SDL_mixer related class, method or function as they are likely
      to fail or might give unpredictable results.
    </desc>
  </func>
  <func name="get_compiled_version">
    <call>get_compiled_version () -> (int, int, int)</call>
    <desc>
      Gets the SDL_mixer version pygame2 was compiled against as three-value tuple.

      This version is built at compile time. It can be used to detect
      which features may not be available through Pygame, if it is used
      as precompiled package using a different version of the SDL_mixer
      library.
    </desc>
  </func>
  <func name="get_error">
    <call>get_error () -> str</call>
    <desc>
      Gets the last SDL_mixer error message occured.

      SDL_mixer maintains an internal error message. This message will
      usually be given to you when a :exc:`pygame2.Error` is raised.

      You will rarely need to call this function.
    </desc>
  </func>
  <func name="get_version">
    <call>get_version () -> (int, int, int)</call>
    <desc>
      Gets the SDL_mixer version pygame2 currently uses as three-value tuple.

      This version is detected at runtime. It can be used to detect
      which features may not be available through Pygame, if it is used
      as precompiled package using a different version of the SDL_mixer
      library.
    </desc>
  </func>
  <func name="init">
    <call>init ([flags]) -> int</call>
    <desc>
      Initializes the underlying SDL_mixer library.

      Initializes the underlying SDL_mixer library using the passed
      mixer flags. The flags indicate, which music library (FLAC, OGG,
      ...) SDL_mixer should initialize and can be a bitwise
      combination of the initialization constants of the
      :mod:`pygame2.sdlmixer.constants` module.

      In case an error occured, an exception will be raised.
    </desc>
  </func>
  <func name="open_audio">
    <call>open_audio (frequency, format, channels, chunksize) -> None</call>
    <desc>
      Initializes the mixer API and prepares the audio hardware for access.

      This must be called before using any other method or class for
      audio output. It initializes the API with a certain *frequency*
      (e.g. 44100 for 44.1 KHz).

      *format* is the sample format that will be used in the
      :class:`Chunk` and :class:`Music` objects and can be one of the
      :data:`AUDIO_XXX` constants.

      *channels* denotes the number of output channels, not the number
      of :class:`Channel` instances and can be 1 for mono or 2 for
      stereo sound.

      *chunksize* is the size of bytes used per output sample to
      stream. The larger the value, the more often the output hooks will
      be called. A good value for chunksize is between 1024 and 4096 on
      most computers (1kB - 4 kB).

      .. note::
      
        You can call this method multiple times with different
        values. In turn, you have to call :func:`close_audio` as often
        as you called :func:`open_audio` to shut anything down.
    </desc>
    <example>
      import pygame2.sdlmixer as mixer
      import pygame2.sdlmixer.constants as mixconst
      ...
      
      mixer.open_audio (22050, mixconst.AUDIO_U16SYS, 2, 2048)
    </example>
  </func>
  <func name="query_spec">
    <call>query_spec () -> (int, int, int, int)</call>
    <desc>
      Queries the actual settings used by the audio device.

      Queries the actual settings used by the audio device and returns
      the setting in the following order:

        * number of times :func:`open_audio` was called
        * current frequency
        * current format
        * current channel setting (stereo or mono)

     See :func:`open_audio` for the typical meaning and values of the
     returned tuple.
    </desc>
  </func>
  <func name="quit">
    <call>quit () -> None</call>
    <desc>
      Shuts down the underlying SDL_mixer library.

      After calling this function, you should not invoke any SDL_mixer
      related class, method or function as they are likely to fail or
      might give unpredictable results.
    </desc>
  </func>
  <func name="was_init">
    <call>was_init () -> bool</call>
    <desc>
      Gets, whether the SDL_mixer library was initialized or not.

      .. note::

         This only checks, whether the **SDL** flag :data:`INIT_AUDIO`
         was set.
    </desc>
  </func>
</module>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.