Version

Quick search

Table Of Contents

Audio Output

Load an audio sound and play it with:

from kivy.core.audio_output import SoundLoader

sound = SoundLoader.load('mytest.wav')
if sound:
    print("Sound found at %s" % sound.source)
    print("Sound is %.3f seconds" % sound.length)
    sound.play()

You should not use the Sound class directly. The class returned by SoundLoader.load() will be the best sound provider for that particular file type, so it might return different Sound classes depending the file type.

Event dispatching and state changes

Audio is often processed in parallel to your code. This means you often need to enter the Kivy eventloop in order to allow events and state changes to be dispatched correctly.

You seldom need to worry about this as Kivy apps typically always require this event loop for the GUI to remain responsive, but it is good to keep this in mind when debugging or running in a REPL (Read-eval-print loop).

Changed in version 1.10.0: The pygst and gi providers have been removed.

Changed in version 1.8.0: There are now 2 distinct Gstreamer implementations: one using Gi/Gst working for both Python 2+3 with Gstreamer 1.0, and one using PyGST working only for Python 2 + Gstreamer 0.10.

Note

The core audio library does not support recording audio. If you require this functionality, please refer to the audiostream extension.

Provider selection

New in version 3.0.0.

By default, Kivy automatically selects an audio provider based on platform defaults and file type. You can override this to use a specific provider.

Querying available providers

To see which providers are available on your system:

from kivy.core.audio_output import SoundLoader
print(SoundLoader.available_providers())  # e.g., ['sdl3', 'ffpyplayer']

Using audio_output_provider parameter

Specify a provider when loading a sound:

from kivy.core.audio_output import SoundLoader

# Load with SDL3 provider
sound = SoundLoader.load('music.mp3', audio_output_provider='sdl3')

# Load with ffpyplayer provider
sound = SoundLoader.load('music.mp3', audio_output_provider='ffpyplayer')

Strict mode

By default, if a requested provider is unavailable or fails, Kivy logs a warning and falls back to other providers. Enable strict mode to raise exceptions instead:

import os
os.environ['KIVY_PROVIDER_STRICT'] = '1'
import kivy

In strict mode:

  • Invalid provider names raise ValueError

  • Provider load failures raise Exception

  • No fallback to other providers occurs

This is useful during development to catch configuration errors immediately.

class kivy.core.audio_output.Sound

Bases: kivy.event.EventDispatcher

Represents a sound to play. This class is abstract, and cannot be used directly.

Use SoundLoader to load a sound.

Events:
on_play: None

Fired when the sound is played.

on_stop: None

Fired when the sound is stopped.

get_pos()

Returns the current position of the audio file. Returns 0 if not playing.

New in version 1.4.1.

property length

Get length of the sound (in seconds).

load()

Load the file into memory.

play()

Play the file.

seek(position)

Go to the <position> (in seconds).

Note

Most sound providers cannot seek when the audio is stopped. Play then seek.

stop()

Stop playback.

unload()

Unload the file from memory.

class kivy.core.audio_output.SoundLoader

Bases: builtins.object

Load a sound, using the best loader for the given file type.

static available_providers()

Return a list of available audio provider names.

The returned names can be used with the audio_provider parameter.

New in version 3.0.0.

Returns:

List of provider name strings (e.g., [‘sdl3’, ‘ffpyplayer’])

static load(filename, audio_output_provider=None) → Sound

Load a sound, and return a Sound() instance.

Parameters:

  • filename – Path to the audio file to load.

  • audio_output_provider –

    Optional provider name (e.g., ‘sdl3’, ‘ffpyplayer’). If specified, only that provider will be used. Use available_providers() to get a list of available providers.

    New in version 3.0.0.

Returns:

A Sound instance, or None if no loader could handle the file.

Raises:

ValueError – If audio_output_provider is specified but not found or doesn’t support the file format (when KIVY_PROVIDER_STRICT=1).

static register(classobj)

Register a new class to load the sound.

« Core Abstraction Camera »