API Reference

This page provides an auto-generated summary of the KitchenSink Audio library’s public API.

Sources

Sources are responsible for acquiring audio data.

class kitchensink.sources.base_source.BaseAudioSource

Bases: object

Abstract base class for audio sources.

An audio source is responsible for acquiring audio data from some origin (e.g., a network stream, a microphone) and forwarding it to a callable ‘sink’.

__init__(sink, disconnect_callback=None, blocksize=None)

Initializes the BaseAudioSource.

Parameters:

• sink (callable) – A callable (function or method) that will receive the audio chunks. It must accept one argument: a NumPy array of audio data.

• disconnect_callback (callable, optional) – A callable that is invoked when the source is disconnected or stops. Defaults to None.

• blocksize (int, optional) – The number of frames per chunk for the source to generate. If None, the source may attempt to use the sink’s preferred blocksize.

async start()

Starts the audio source. This method should handle any setup required, begin acquiring audio, and continue until stop() is called or the source ends.

async stop()

Signals the audio source to gracefully stop acquiring audio and clean up resources.

class kitchensink.sources.network_audio_source.TCPServerAudioSource

Bases: BaseAudioSource

An audio source that listens for a single incoming TCP connection, receives audio data, processes it, and pushes it to a provided sink.

__init__(sink, disconnect_callback=None, host='0.0.0.0', port=8123, gain_factor=1.0, blocksize=960)

Initializes the TCPServerAudioSource.

Parameters:

• sink – A callable that accepts one argument (the audio chunk as a NumPy array).

• disconnect_callback (callable, optional) – A callable that is invoked when a client disconnects.

• host (str) – The host address to listen on.

• port (int) – The port to listen on.

• gain_factor (float) – Factor to amplify the incoming audio.

• blocksize (int) – The number of frames per audio chunk.

async start()

Starts the server to listen for an audio source.

async stop()

Stops the audio server gracefully.

class kitchensink.sources.raw_websocket_audio_source.RawWebSocketServerAudioSource

Bases: BaseAudioSource

An audio source that listens for a single WebSocket client, receives raw binary audio messages, and forwards them to a sink. This component is optimized for performance and expects only audio data.

__init__(sink, disconnect_callback=None, host='0.0.0.0', port=8765, blocksize=None)

Initializes the RawWebSocketServerAudioSource.

Parameters:

• sink – Passed to BaseAudioSource.

• disconnect_callback – Passed to BaseAudioSource.

• host (str) – The host address to listen on.

• port (int) – The port to listen on.

• blocksize (int, optional) – The preferred blocksize for audio chunks. Note: This source processes whatever it receives.

async start()

Starts the WebSocket server.

async stop()

Stops the WebSocket server gracefully.

class kitchensink.sources.typed_websocket_audio_source.TypedWebSocketServerAudioSource

Bases: BaseAudioSource

An audio source that listens for a WebSocket client and handles typed JSON messages. It can process both audio streams and other message types like text or events.

Expected message format (JSON string): {

“type”: “audio” | “text” | “custom_event”, “payload”: “…”

} For “audio”, the payload should be a Base64-encoded string of the raw audio bytes.

__init__(sink, disconnect_callback=None, on_message_callback=None, host='0.0.0.0', port=8765, blocksize=None)

Initializes the TypedWebSocketServerAudioSource.

Parameters:

• sink – Passed to BaseAudioSource.

• disconnect_callback – Passed to BaseAudioSource.

• on_message_callback (callable, optional) – A function to call for non-audio messages. It receives two arguments: the message type (str) and the message payload (dict/str).

• host (str) – The host address to listen on.

• port (int) – The port to listen on.

• blocksize (int, optional) – The preferred blocksize for audio chunks. Note: This source processes whatever it receives.

async start()

Starts the typed WebSocket server.

async stop()

Stops the typed WebSocket server.

Sinks

Sinks are the destination for audio data.

class kitchensink.sinks.base_sink.BaseAudioSink

Bases: object

Abstract base class for audio sinks.

An audio sink is a destination for audio data. It takes audio chunks (as NumPy arrays) and performs an action, such as playing them through speakers, writing them to a file, or broadcasting them over a network.

__init__(sample_rate=16000, channels=1, dtype='int16', blocksize=None)

Initializes the BaseAudioSink.

Parameters:

• sample_rate (int) – The sample rate of the audio (e.g., 16000 for speech).

• channels (int) – The number of audio channels (e.g., 1 for mono).

• dtype (str) – The data type of the audio samples (e.g., ‘int16’).

• blocksize (int, optional) – The preferred number of frames per chunk

• flow. (for this sink. A source can use this to optimize the data)

• None (Defaults to)

clear()

Clears any audio data currently held in the sink’s internal buffer.

close()

Signals the sink to gracefully stop its operations and clean up any resources. Sets an event that should be respected by any background processing loops.

push_chunk(chunk)

Receives an audio chunk and adds it to the internal buffer for processing. This is the primary method used to feed data to the sink.

Parameters:

chunk (np.ndarray) – A NumPy array containing the audio data for the chunk.

async start()

Optional method to initialize and start the sink. This is particularly important for sinks that need to perform asynchronous setup. This base implementation does nothing and can be overridden if needed.

class kitchensink.sinks.network_audio_sink.TCPClientAudioSink

Bases: BaseAudioSink

An audio sink that connects to a TCP server and sends audio chunks.

__init__(host, port, sample_rate=16000, channels=1, dtype='int16', blocksize=None)

Initializes the TCPClientAudioSink.

Parameters:

• host (str) – The hostname or IP address of the server to connect to.

• port (int) – The port of the server.

• sample_rate – Passed to BaseAudioSink.

• channels – Passed to BaseAudioSink.

• dtype – Passed to BaseAudioSink.

• blocksize – Passed to BaseAudioSink.

close()

Closes the connection and stops the sender thread.

async start()

Establishes the connection to the TCP server and starts the sending loop.

class kitchensink.sinks.raw_websocket_audio_sink.RawWebSocketClientAudioSink

Bases: BaseAudioSink

An audio sink that connects to a WebSocket server and sends raw audio chunks as binary messages. This component is optimized for performance.

__init__(uri, sample_rate=16000, channels=1, dtype='int16', blocksize=None)

Initializes the RawWebSocketClientAudioSink.

Parameters:

• uri (str) – The WebSocket URI to connect to (e.g., “ws://localhost:8765”).

• sample_rate – Passed to BaseAudioSink.

• channels – Passed to BaseAudioSink.

• dtype – Passed to BaseAudioSink.

• blocksize – Passed to BaseAudioSink.

close()

Closes the WebSocket connection.

async start()

Establishes the connection to the WebSocket server.

class kitchensink.sinks.typed_websocket_audio_sink.TypedWebSocketClientAudioSink

Bases: BaseAudioSink

An audio sink that connects to a typed WebSocket server and sends both audio (as Base64 JSON) and other message types.

__init__(uri, sample_rate=16000, channels=1, dtype='int16', blocksize=None)

Initializes the TypedWebSocketClientAudioSink.

Parameters:

• uri (str) – The WebSocket URI to connect to (e.g., “ws://localhost:8765”).

• sample_rate – Passed to BaseAudioSink.

• channels – Passed to BaseAudioSink.

• dtype – Passed to BaseAudioSink.

• blocksize – Passed to BaseAudioSink.

close()

Closes the WebSocket connection.

push_chunk(chunk)

Receives an audio chunk, encodes it, and schedules it to be sent. This is designed to be called from a non-async (e.g., audio callback) thread.

Parameters:

chunk (ndarray)

async send_message(msg_type, payload)

Sends a typed message to the WebSocket server. This method is a coroutine and must be awaited.

Parameters:

• msg_type (str) – The type of the message (e.g., “audio”, “text”).

• payload – The data to send. Must be JSON-serializable.

async start()

Establishes the connection to the WebSocket server.

Utilities