Booombox endpoints

Boombox endpoints.

Endpoints are classes defining possible inputs and outputs of Boombox. Each endpoint represents a different media format and has appropriate attributes that describe it.

Examples:

MP4(“path/to/file.mp4”) - an endpoint defining an MP4 container. If provided for input, then Boombox will read a MP4 file from this location. If provided for output, then Boombox will create a file at that location and store the produced stream in it in MP4 format.
HLS(“path/to/playlist”) - an endpoint defining a HLS playlist. Only output is supported. If used, a playlist will be created in the specified location.
WebRTC(“ws://host:port”) - an endpoint defining a WebRTC connection. Both input and output is supported. Websocket at the provided URL is used as a signaling channel.

class boombox.endpoints.BoomboxEndpoint(*, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None)[source]

Bases: ABC

Abstract base class of a Boombox endpoint.

Boombox endpoints are the definitions of Boombox inputs and outputs. This class is a base class for these definitions. When creating a Boombox instance it expects a specification of it’s input and output as BoomboxEndpoints.

Attributes:

transcoding_policy{None, “if_needed”, “always”, “never”}, optional: Allowed only for output. The default transcoding behavior is “if_needed”, which means that if the format of the media is the same for input and output, then the stream is not decoded and encoded. This approach saves resources and time, but in some cases transcoding can be necessary. To force transcoding regardless if the formats differ or not, this option can be set to “always”. If set to “never”, Boombox will never transcode, raising if the desired operation can’t be done without transcoding.

transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None

serialize(direction: Literal['input', 'output']) → tuple[source]

Serializes itself to an Elixir-compatible term.

To allow Pyrlang to send the endpoint definition to Elixir it first needs to be serialized into an Elixir-compatible term. This function serializes the endpoint to a tuple that matches the structure of Boombox endpoints in Elixir.

Returns:

endpoint_tupletuple: A tuple representing the endpoint. The first element is an Atom representing the endpoint name, next elements are required field values and in case there are any keyword fields they are in the last element.

class boombox.endpoints.RawData(*, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, audio: bool, video: bool, audio_rate: int | None = None, audio_channels: int | None = None, audio_format: Literal['s8', 'u8', 's16le', 'u16le', 's16be', 'u16be', 's24le', 'u24le', 's24be', 'u24be', 's32le', 'u32le', 's32be', 'u32be', 'f32le', 'f32be', 'f64le', 'f64be'] | None = None, video_width: int | None = None, video_height: int | None = None, pace_control: bool | None = None, is_live: bool | None = None)[source]

Bases: BoomboxEndpoint

Endpoint for communication through numpy arrays containing raw media data.

This endpoint defines the behavior of Boombox allowing for interacting with Python code directly. For more details refer to Boombox class.

Attributes:

audio, videobool: Determines whether this endpoint will accept/produce video packets, audio packets, or both.
audio_rateint, optional: Applicable only when audio is set to True and the endpoint defines the output. Determines the sample rate of the produced stream (number of samples per second).
audio_channelsint, optional: Applicable only when audio is set to True and the endpoint defines the output. Determines how many channels does the produced stream have. The channels are interleaved.
audio_formatAudioSampleFormat, optional: Applicable only when audio is set to True and the endpoint defines the output. Determines the sample format of the produced stream.
video_width, video_heightint, optional: Applicable only when video is set to True and the endpoint defines the output. Determines the dimensions of the produced video stream.
pace_controlbool, optional: Allowed only for output. If true the incoming streams will be passed to the output according to their timestamps, if not they will be passed as fast as possible. True by default.
is_livebool, optional: Allowed only for input. If true then Boombox will assume that packets will be provided in realtime and won’t control their pace when passing them to the output. False by default.

audio: bool

video: bool

audio_rate: int | None = None

audio_channels: int | None = None

audio_format: Literal['s8', 'u8', 's16le', 'u16le', 's16be', 'u16be', 's24le', 'u24le', 's24be', 'u24be', 's32le', 'u32le', 's32be', 'u32be', 'f32le', 'f32be', 'f64le', 'f64be'] | None = None

video_width: int | None = None

video_height: int | None = None

pace_control: bool | None = None

is_live: bool | None = None

class boombox.endpoints.StorageEndpoint(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: BoomboxEndpoint, ABC

Abstract base class for storage endpoints.

Storage endpoints are endpoints that are used for putting the media in some type of storage.

Attributes:

locationstr: A path to a file or an HTTP URL, location where the media should be read from or written to.
transport{None, “file”, “http”}, optional:: An optional attribute that explicitly states whether a file or HTTP storage should be assumed. If not provided transport will be determined from location - paths will resolve to “file” location, HTTP URLs to “http”.

location: str

transport: Literal['file', 'http'] | None = None

class boombox.endpoints.H264(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None, framerate: tuple[int, int] = (30, 1))[source]

Bases: StorageEndpoint

Storage endpoint for H264 codec.

When used for output the stored stream will have Annex-B format, and when reading the stream has to already be in Annex-B format.

Attributes:

frameratetuple[int, int], default=(30, 1): Framerate of the stream, where the tuple defines the numerator and denominator of it. If not provided 30 FPS will be assumed.

framerate: tuple[int, int] = (30, 1)

class boombox.endpoints.H265(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None, framerate: tuple[int, int] = (30, 1))[source]

Bases: StorageEndpoint

Storage endpoint for H265 codec.

When used for output the stored stream will have Annex-B format, when reading the stream has to already be in Annex-B format.

Attributes:

frameratetuple[int, int], default=(30, 1): Framerate of the stream, where the tuple defines the numerator and denominator of it. If not provided 30 FPS will be assumed.

framerate: tuple[int, int] = (30, 1)

class boombox.endpoints.MP4(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for MP4 container format.

class boombox.endpoints.AAC(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for AAC codec.

class boombox.endpoints.WAV(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for WAV format.

class boombox.endpoints.MP3(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for MP3 format.

class boombox.endpoints.IVF(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for IVF container format.

class boombox.endpoints.Ogg(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, transport: Literal['file', 'http'] | None = None)[source]

Bases: StorageEndpoint

Endpoint for Ogg container format.

class boombox.endpoints.WebRTC(signaling: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None)[source]

Bases: BoomboxEndpoint

Endpoint for communication over WebRTC.

Attributes:

signalingstr: URL of the WebSocket that is the signaling channel of the WebRTC connection.

signaling: str

class boombox.endpoints.WHIP(url: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, token: str)[source]

Bases: BoomboxEndpoint

Endpoint for communication over WebRTC-HTTP ingestion protocol (WHIP).

Attributes:

urlstr: HTTP url of the WHIP server.
tokenstr: Token used for authentication and authorization.

url: str

token: str

class boombox.endpoints.HLS(location: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, mode: Literal['vod', 'live'] = 'vod')[source]

Bases: BoomboxEndpoint

Endpoint for HTTP Live Streaming. Boombox supports fetching HLS streams as input and creating HLS playlists as output.

Attributes:

locationstr: If set for input it should be an URL to location from which to fetch the HLS stream. If set for output it’s a path to the location where the HLS playlist will be created. If the path is to a directory, then an “index.m3u8” manifest file and the other files will be created If a .m3u8 path is provided, the manifest will be created at that location, and all associated HLS files will be stored in the same directory.
mode{“vod”, “live”}, optional: If set for output then it determines if the session is live or a VOD type of broadcast. It can influence type of metadata inserted into the playlist’s manifest.

location: str

mode: Literal['vod', 'live'] = 'vod'

class boombox.endpoints.RTMP(url: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None)[source]

Bases: BoomboxEndpoint

Endpoint for communication over Real-Time Messaging Protocol (RTMP).

Currently Boombox supports only client-side functionality - streaming media to a RTMP server.

Attributes:

urlstr: URL of a RTMP server.

url: str

class boombox.endpoints.RTSP(url: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None)[source]

Bases: BoomboxEndpoint

Endpoint for communication over Real-Time Streaming Protocol (RTSP).

Currently Boombox supports only client-side functionality - receiving media from a RTSP server.

Attributes:

urlstr: URL of a RTSP server.

url: str

Bases: BoomboxEndpoint

Endpoint for communication over Real-time Transport Protocol (RTP).

Since RTP doesn’t incorporate any negotiation a lot of information about streamed media has to be provided manually via the attributes.

Attributes:

portint: Port on which Boombox will receive the stream or to which it will send it to.
addressstr, optional: IP address which Boombox will send the stream to.
audio_encoding, video_encodingstr, optional: Encoding name of given media type. Has to be the same as it would be in rtpmap attribute of a SDP description.
audio_payload_type, video_payload_typeint, optional: Payload type of given media type. Has to be the same as it would be in rtpmap attribute of a SDP description.
audio_clock_rate, video_clock_rateint, optional: Clock rate of given media type. Has to be the same as it would be in rtpmap attribute of a SDP description.
aac_bitrate_mode{None, “lbr”, “hbr”}: Applicable only for AAC payload. Defines which mode should be assumed/set when depayloading/payloading.
audio_specific_configbytes, optional: Applicable only for AAC payload. Contains crucial information about the stream and has to be obtained from a side channel.
vps, pps, spsbytes, optional: Applicable only for H264 and H265 payloads. Parameter sets, could be obtained from a side channel. They contain information about the encoded stream.

port: int

address: str | None = None

video_encoding: str | None = None

video_payload_type: int | None = None

video_clock_rate: int | None = None

audio_encoding: str | None = None

audio_payload_type: int | None = None

audio_clock_rate: int | None = None

aac_bitrate_mode: Literal['lbr', 'hbr'] | None = None

audio_specific_config: bytes | None = None

vps: bytes | None = None

pps: bytes | None = None

sps: bytes | None = None

class boombox.endpoints.SRT(url: str, *, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None, stream_id: str, password: str)[source]

Bases: BoomboxEndpoint

Endpoint for communication over Secure Reliable Transport (SRT) protocol.

When using this endpoint as input, Boombox will act as an SRT server and expect connections from clients at the provided address. When using as output, Boombox will act as an SRT client and try to connect to a server under the provided address.

Attributes:

urlstr: Address of the SRT server in the form of <ip>:<port>. When using this endpoint as input, this field determines on which address the server will listen for connections. When using for output, it will determine to what address to connect.
stream_idstr, optional: ID of the stream. When using this endpoint as input, this field determines the ID of the stream which the server will accept. When using for output, it will determine ID of the stream being sent.
passwordstr, optional: Password used to authenticate the connection. When using this endpoint as input, this field determines the password the server will require from clients when connecting. When using for output, it will determine what password the client will use to authenticate.

url: str

stream_id: str

password: str

class boombox.endpoints.Player(*, transcoding_policy: Literal['if_needed', 'always', 'never'] | None = None)[source]

Bases: BoomboxEndpoint

Endpoint that plays the output stream with the SDL2 media player.