Usage

Quick start—a cross-platform player looks like this:

from boombox import BoomBox  # 📾 power on

boombox = BoomBox("There's_no_stoppin_us.opus")  # load 🖭

boombox.play()  # hit the [▶] button

The play function also returns the instance, so if in a hurry one could do:

boombox = BoomBox(slow_jam).play()  # or
BoomBox(slow_jam).play()

The latter less efficient for multiple calls, of course. There are a number of other keyword parameters that can be passed. Such as:

• wait

• timeout_ms

• duration_ms

• binary_path (ChildBoomBox only, to a CLI player)

Not all arguments are supported on every implementation, but they will not balk if given.

Implementations

There are a number of underlying implementations if you’d like to pick a specific one and bypass the platform default:

• Windows

  • WinBoomBox (default, wav only)

  • PyAudioBoomBox - PyAudio (wav only)

  • ChildBoomBox - Command-line player (powershell, others)

• Mac OSX:

  • MacOSBoomBox - PyObjc (default, multiformat)

  • PyAudioBoomBox - PyAudio (wav only)

  • ChildBoomBox - Command-line player (afplay, others)

• POSIX:

  • GstBoomBox - Gstreamer (default, multiformat)

  • PyAudioBoomBox - PyAudio (wav only)

  • ChildBoomBox - Command-line player (paplay, aplay, others)

Simply add an import to your script to choose a different one:

from boombox import PyAudioBoomBox as BoomBox

You may have to install one of the audio libraries above for all of the functionality of Boom Box to work.

⏵ pip install --user boombox[all]  # or pyaudio, pyobjc, pygobject, etc

Playback Control

╭───────────────────────────────────────────╮
│ ╭───────────────────────────────────────╮ │
│ │ ╭───────────────────────────────────╮ │ │
│ │ │ /\ :  Electric Boogaloo     90 min│ │ │
│ │ │/──\: .....................  NR [✓]│ │ │
│ │ ╰───────────────────────────────────╯ │ │
│ │      //─\\   ╭....:....╮   //─\\      │ │
│ │     ││( )││  │)       (│  ││( )││     │ │
│ │      \\─//   ╰....:....╯   \\─//      │ │
│ │       _ _ ._  _ _ .__|_ _.._  _       │ │
│ │      (_(_)│ |(_(/_│  │_(_||_)(/_      │ │
│ │               low noise   |           │ │
│ ╰─────── ─────────────────────── ───────╯ │
│        /    []             []    \        │
│       /  ()                   ()  \       │
╰──────/─────────────────────────────\──────╯

A simple playback interface is returned by the instance:

boombox.stop()  # Enough!
boombox.play()  # One more time!

Tone Generation

Tones may be generated like so:

boombox.play_tone(frequency_hz, duration_ms, volume=.1)

▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂▂
╲▂▂▂▂╱╲▂▂▂▂╱╲▂▂▂
▔╲▂▂▂╱▔╲▂▂▂╱▔╲▂▂
▔▔╲▂▂╱▔▔╲▂▂╱▔▔╲▂
▔▔▔╲▂╱▔▔▔╲▂╱▔▔▔╲
▔▔▔▔╲╱▔▔▔▔╲╱▔▔▔▔
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

┏┓╻┏━┓   ┏━┓┏┓╻┏━╸   ╺┳┓┏━┓┏━╸┏━┓   ╻╺┳╸   ┏┓ ┏━╸╺┳╸╺┳╸┏━╸┏━┓   ╻
┃┗┫┃ ┃   ┃ ┃┃┗┫┣╸     ┃┃┃ ┃┣╸ ┗━┓   ┃ ┃    ┣┻┓┣╸  ┃  ┃ ┣╸ ┣┳┛   ╹
╹ ╹┗━┛   ┗━┛╹ ╹┗━╸   ╺┻┛┗━┛┗━╸┗━┛   ╹ ╹    ┗━┛┗━╸ ╹  ╹ ┗━╸╹┗╸   ╹