Booombox

Module containing Boombox class and media packet classes.

class boombox.boombox.Boombox(input: BoomboxEndpoint | str, output: BoomboxEndpoint | str)

Bases: Process

Boombox is a tool that allows to transform a media stream from one format into another.

When creating an instance of Boombox the input and output are specified by providing an appropriate endpoint object for each of them. These objects define the format and its parameters that are used for the input or output, whichever they were provided for.

For example, if an RTMP("rtmp://my.stream.source:2137/app/key") endpoint was provided for input and MP4("path/to/target.mp4") for output, then Boombox will become a RTMP server, wait for clients to connect and save the acquired stream to a .mp4 file at the provided location.

Input and output can also be specified by strings alone, as in "rtmp://my.stream.source:2137/app/key" or "path/to/target.mp4", and Boombox will automatically interpret them as RTMP and MP4 endpoints.

For more information about endpoints and to see supported formats refer to endpoints.

One of the main reasons to use Boombox in a Python project is to interact with it from Python code directly. This can be achieved with RawData endpoint, that enables methods allowing for this interactions.

If the input is defined by RawData, Boombox will accept packets provided by write() method. This method will return once Boombox has processed the provided packet and is ready for the next one. Once Boombox should stop accepting more packets, close() should be called to informing it about the end of the stream. Calling this method can be skipped if opening Boombox using a context manager.

If the output is defined by RawData, Boombox will produce packets that are yielded by a generator returned by read().

These methods operate on AudioPacket and VideoPacket objects. These objects contain raw media data and accompanying metadata.

If not using RawData endpoints Boombox operates fully asynchronously, it’ll work in the background if not interacted with. For more control regarding the termination of Boombox refer to close(), wait() and kill() methods.

Parameters:

input, outputBoomboxEndpoint or str

Definition of an input or output of Boombox. Can be provided explicitly by an appropriate BoomboxEndpoint or a string of a path to a file or an URL, that Boombox will attempt to interpret as an endpoint.

Attributes:

loggerClassVar[logging.Logger]

Logger used in this class

logger: ClassVar[logging.Logger] = <Logger boombox.boombox (WARNING)>

read() → Generator[AudioPacket | VideoPacket, None, None]

Read media packets produced by Boombox.

Enabled only if Boombox has been initialized with output defined with an RawData endpoint.

This generator yields packets as fast as Boombox produces them.

Yields:

AudioPacket or VideoPacket

Raw media packets produced by Boombox.

Raises:

RuntimeError

If Boombox’s output was not defined by an RawData endpoint.

write(packet: AudioPacket | VideoPacket) → bool

Write packets to Boombox.

Enabled only if Boombox has been initialized with input defined with an RawData endpoint and if Boombox hasn’t already finished accepting packets.

This method provides Boombox with a packet to process and returns once Boombox is ready to accept the next packet.

Parameters:

packetAudioPacket or VideoPacket

Raw media packet to be consumed by Boombox.

Returns:

finishedbool

If true then Boombox has finished accepting packets and closed its input for any further ones. Once it finishes processing the previously provided packet, it will terminate.

Raises:

RuntimeError

If Boombox’s input was not defined with an RawData endpoint or if Boombox has already finished accepting packets.

close(wait: bool = True, kill: bool = False) → None

Closes Boombox for writing or reading.

Enabled only if Boombox has been initialized with input or output defined with a RawData endpoint.

This method informs Boombox that it shouldn’t expect or produce any more packets.

Parameters:

waitbool, default=True

Determines whether this method should wait until Boombox finishes it’s operation and only then return, or if it should return immediately and let Boombox finish in the background. Ignored if kill set to true.

killbool, default=False

Determines whether Boombox should be killed without waiting for it to gracefully finish it’s operation. If True this method will return immediately.

Raises:

RuntimeError

If neither of Boombox’s input or output was defined with a RawData endpoint.

wait() → None

Waits until Boombox finishes it’s operation and then returns.

kill() → None

Forces Boombox to exit without waiting for it to gracefully finish it’s operation.

class boombox.boombox.VideoPacket(payload: ndarray, timestamp: int)

Bases: object

A Boombox packet containing raw video.

Objects of this class are used when writing/reading raw video data to/from Boombox through the usage of RawData endpoint.

Attributes:

payloadnp.ndarray

Raw data of a single frame of the video stream. Shape of the array is (width, height, channels).

timestampint

Timestamp of the frame in milliseconds.

payload: ndarray

timestamp: int

class boombox.boombox.AudioPacket(payload: ndarray, timestamp: int, sample_rate: int, channels: int)

Bases: object

A Boombox packet containing raw audio.

Objects of this class are used when writing/reading raw audio data to/from Boombox through the usage of RawData endpoint.

Attributes:

payloadnp.ndarray

Raw data of an audio chunk of the video stream. The array is one-dimentional.

timestampint

Timestamp of the first sample in the chunk in milliseconds.

sample_rateint

Number of audio samples per second.

channelsint

Number of channels interleaved in the stream.

payload: ndarray

timestamp: int

sample_rate: int

channels: int