Skip to main content

audioplayer is a cross platform Python 3 module for playing sounds (mp3, wav, ...)

Project description


audioplayer is a cross platform Python 3 package for playing sounds (mp3, wav, ...). It provides the key features of an audio player, such as opening a media file, playing (loop/block), pausing, resuming, stopping, and setting the playback volume.

I created this package to provide sound functionality to my game library game2dboard, but I decided to publish it separately.

Suported systems (see full list):

  • GNU/Linux (PC, Raspberry Pi, ...)
  • Windows
  • macOS

Inspired by (and with a few lines of codes from) the playsound module.




In Linux, you need to install PyGObject and others dependencies.

Ubuntu/Debian/Raspberry Pi OS:

sudo apt-get install python-gst-1.0 \ 
                     gir1.2-gstreamer-1.0 \ 
                     gstreamer1.0-tools \
                     gstreamer1.0-plugins-good \


sudo yum install -y python-gstreamer1 \ 
                    gstreamer1-plugins-good \


In macOS, you need to install PyObjC bridge.

pip3 install PyObjC --user


The recommended way to install audioplayer is using the Python pip (or pip3) installer.

pip3 install audioplayer

If you don't have administrator privileges, install in your home folder.

pip3 install audioplayer --user

You can install the latest release by cloning this repository.

git clone 
cd audioplayer
python3 install --user


The API is documented bellow and within the docstrings.

After install, you can use this code to test (replace "path/to/somemusic.mp3"):

from audioplayer import AudioPlayer

# Playback stops when the object is destroyed (GC'ed), so save a reference to the object for non-blocking playback.



  • audioplayer.AudioPlayer(filename)
    Creates the player.

    • filename : str – The file name with extension (.mp3, .wav, ...)

    Raise: FileNotFoundError() : The file does not exist.


  • filename : str (readonly)
    The file name as provided in the constructor.

  • fullfilename : str (readonly)
    The file name with full path.

  • volume : int
    Gets or sets the current volume (in %) of the audio (0 — 100)


  • play(loop=False, block=False)
    Starts audio playback.

    • loop (bool) – Sets whether to repeat the track automatically when finished.
    • block (bool) – If true, blocks the thread until playback ends.

    Raise: AudioPlayerError(): Failed to play.

  • pause()
    Pauses audio playback.

  • resume()
    Resumes audio playback.

  • stop()
    Stops audio playback. Can play again.

  • close()
    Closes device, releasing resources. Can't play again.

Suported Systems

audioPlayer has been tested on the following platforms:

OS Details mp3 wav ogg mid
GNU/Linux Mint 19 (Cinnamon)
GNU/Linux Xubuntu 20.04
GNU/Linux Raspberry Pi OS
Windows Windows 10 x64
macOS Catalina (Python 3.8)

?: Not yet tested

Let me know if you are using on another system/distro/version!

What's in the roadmap?

  • .seek(position) : Moves playback to the specified position.
  • .state : Current state (playing, stopped, paused, ...)
  • .speed = value : Gets/sets playback speed.
  • Callbacks: when state changed, when position changed by a delta, ...

How to Contribute

Submitting an issue

Use the issue tracker to submit bug reports and features or enhancements requests.


You can contribute by translating this document into other languages ​​(except en and pt_br).

Submitting a pull request

If you can improve anything in this project, feel free to add a pull request.


audioplayer is under MIT license. It can be reused within proprietary software provided that all copies of the licensed software include a copy of the MIT License terms and the copyright notice.

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

audioplayer-0.6.tar.gz (6.5 kB view hashes)

Uploaded source

Built Distribution

audioplayer-0.6-py3-none-any.whl (8.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page