Reference

Warning

There is no compatibility promise until 1.0.0 is released. Small breaking changes are possible.

See also

Alphabetical index is available here.

roc_context

#include <roc/context.h>
typedef struct roc_context roc_context

Shared context.

Context contains memory pools and network worker threads, shared among objects attached to the context. It is allowed both to create a separate context for every object, or to create a single context shared between multiple objects.

Life cycle

A context is created using roc_context_open() and destroyed using roc_context_close(). Objects can be attached and detached to an opened context at any moment from any thread. However, the user should ensure that the context is not closed until there are no objects attached to the context.

Thread safety

Can be used concurrently

int roc_context_open(const roc_context_config *config, roc_context **result)

Open a new context.

Allocates and initializes a new context. May start some background threads. Overrides the provided result pointer with the newly created context.

Parameters

  • config should point to an initialized config

  • result should point to an unitialized roc_context pointer

Returns

  • returns zero if the context was successfully created

  • returns a negative value if the arguments are invalid

  • returns a negative value if there are not enough resources

Ownership

  • passes the ownership of result to the user; the user is responsible to call roc_context_close() to free it

int roc_context_register_encoding(roc_context *context, int encoding_id, const roc_media_encoding *encoding)

Register custom encoding.

Registers encoding with given encoding_id. Registered encodings complement built-in encodings defined by roc_packet_encoding enum. Whenever you need to specify packet encoding, you can use both built-in and registered encodings.

On sender, you should register custom encoding and set to packet_encoding field of roc_sender_config, if you need to force specific encoding of packets, but built-in set of encodings is not enough.

On receiver, you should register custom encoding with same id and specification, if you did so on sender, and you’re not using any signaling protocol (like RTSP) that is capable of automatic exchange of encoding information.

In case of RTP, encoding id is mapped directly to payload type field (PT).

Parameters

  • context should point to an opened context

  • encoding_id should be encoding identifier in range [1; 127]

  • encoding should point to valid encoding specification

Returns

  • returns zero if encoding was successfully registered

  • returns a negative value if the arguments are invalid

  • returns a negative value if encoding with given identifier already exists

Ownership

  • doesn’t take or share the ownership of encoding; copies its contents to internal encodings table

int roc_context_close(roc_context *context)

Close the context.

Stops any started background threads, deinitializes and deallocates the context. The user should ensure that nobody uses the context during and after this call.

If this function fails, the context is kept opened.

Parameters

  • context should point to an opened context

Returns

  • returns zero if the context was successfully closed

  • returns a negative value if the arguments are invalid

  • returns a negative value if there are objects attached to the context

Ownership

  • ends the user ownership of context; it can’t be used anymore after the function returns

roc_sender

#include <roc/sender.h>
typedef struct roc_sender roc_sender

Sender node.

Sender gets an audio stream from the user, encodes it into network packets, and transmits them to a remote receiver.

Context

Sender is automatically attached to a context when opened and detached from it when closed. The user should not close the context until the sender is closed.

Sender work consists of two parts: stream encoding and packet transmission. The encoding part is performed in the sender itself, and the transmission part is performed in the context network worker threads.

Life cycle

  • A sender is created using roc_sender_open().

  • Optionally, the sender parameters may be fine-tuned using roc_sender_configure().

  • The sender either binds local endpoints using roc_sender_bind(), allowing receivers connecting to them, or itself connects to remote receiver endpoints using roc_sender_connect(). What approach to use is up to the user.

  • The audio stream is iteratively written to the sender using roc_sender_write(). The sender encodes the stream into packets and send to connected receiver(s).

  • The sender is destroyed using roc_sender_close().

Slots, interfaces, and endpoints

Sender has one or multiple slots, which may be independently bound or connected. Slots may be used to connect sender to multiple receivers. Slots are numbered from zero and are created automatically. In simple cases just use ROC_SLOT_DEFAULT.

Each slot has its own set of interfaces, one per each type defined in roc_interface. The interface defines the type of the communication with the remote node and the set of the protocols supported by it.

Supported actions with the interface:

  • Call roc_sender_bind() to bind the interface to a local roc_endpoint. In this case the sender accepts connections from receivers and sends media stream to all connected receivers.

  • Call roc_sender_connect() to connect the interface to a remote roc_endpoint. In this case the sender initiates connection to the receiver and starts sending media stream to it.

Supported interface configurations:

Slots can be removed using roc_sender_unlink(). Removing a slot also removes all its interfaces and terminates all associated connections.

Slots can be added and removed at any time on fly and from any thread. It is safe to do it from another thread concurrently with writing frames. Operations with slots won’t block concurrent writes.

FEC scheme

If ROC_INTERFACE_CONSOLIDATED is used, it automatically creates all necessary transport interfaces and the user should not bother about them.

Otherwise, the user should manually configure ROC_INTERFACE_AUDIO_SOURCE and ROC_INTERFACE_AUDIO_REPAIR interfaces:

The protocols for the two interfaces should correspond to each other and to the FEC scheme. For example, if ROC_FEC_ENCODING_RS8M is used, the protocols should be ROC_PROTO_RTP_RS8M_SOURCE and ROC_PROTO_RS8M_REPAIR.

Sample rate

If the sample rate of the user frames and the sample rate of the network packets are different, the sender employs resampler to convert one rate to another.

Resampling is a quite time-consuming operation. The user can choose between several resampler profiles providing different compromises between CPU consumption and quality.

Clock source

Sender should encode samples at a constant rate that is configured when the sender is created. There are two ways to accomplish this:

  • If the user enabled internal clock (ROC_CLOCK_SOURCE_INTERNAL), the sender employs a CPU timer to block writes until it’s time to encode the next bunch of samples according to the configured sample rate.

    This mode is useful when the user gets samples from a non-realtime source, e.g. from an audio file.

  • If the user enabled external clock (ROC_CLOCK_SOURCE_EXTERNAL), the samples written to the sender are encoded and sent immediately, and hence the user is responsible to call write operation according to the sample rate.

    This mode is useful when the user gets samples from a realtime source with its own clock, e.g. from an audio device. Internal clock should not be used in this case because the audio device and the CPU might have slightly different clocks, and the difference will eventually lead to an underrun or an overrun.

Thread safety

Can be used concurrently.

int roc_sender_open(roc_context *context, const roc_sender_config *config, roc_sender **result)

Open a new sender.

Allocates and initializes a new sender, and attaches it to the context.

Parameters

  • context should point to an opened context

  • config should point to an initialized config

  • result should point to an unitialized roc_sender pointer

Returns

  • returns zero if the sender was successfully created

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

  • passes the ownership of result to the user; the user is responsible to call roc_sender_close() to free it

  • attaches created sender to context; the user should not close context before closing sender

int roc_sender_configure(roc_sender *sender, roc_slot slot, roc_interface iface, const roc_interface_config *config)

Set sender interface configuration.

Updates configuration of specified interface of specified slot. If called, the call should be done before calling roc_sender_bind() or roc_sender_connect() for the same interface.

Automatically initializes slot with given index if it’s used first time.

If an error happens during configure, the whole slot is disabled and marked broken. The slot index remains reserved. The user is responsible for removing the slot using roc_sender_unlink(), after which slot index can be reused.

Parameters

  • sender should point to an opened sender

  • slot specifies the sender slot

  • iface specifies the sender interface

  • config should be point to an initialized config

Returns

  • returns zero if config was successfully updated

  • returns a negative value if the arguments are invalid

  • returns a negative value if slot is already bound or connected

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

int roc_sender_connect(roc_sender *sender, roc_slot slot, roc_interface iface, const roc_endpoint *endpoint)

Connect the sender interface to a remote receiver endpoint.

Checks that the endpoint is valid and supported by the interface, allocates a new outgoing port, and connects it to the remote endpoint.

Each slot’s interface can be bound or connected only once. May be called multiple times for different slots or interfaces.

Automatically initializes slot with given index if it’s used first time.

If an error happens during connect, the whole slot is disabled and marked broken. The slot index remains reserved. The user is responsible for removing the slot using roc_sender_unlink(), after which slot index can be reused.

Parameters

  • sender should point to an opened sender

  • slot specifies the sender slot

  • iface specifies the sender interface

  • endpoint specifies the receiver endpoint

Returns

  • returns zero if the sender was successfully connected

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of endpoint; it may be safely deallocated after the function returns

int roc_sender_query(roc_sender *sender, roc_slot slot, roc_sender_metrics *metrics)

Query sender slot metrics.

Reads sender slot metrics into provided struct.

Parameters

  • sender should point to an opened sender

  • slot specifies the sender slot

  • metrics specifies struct where to write metrics

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

Ownership

  • doesn’t take or share the ownership of metrics; it may be safely deallocated after the function returns

Delete sender slot.

Disconnects, unbinds, and removes all slot interfaces and removes the slot. All associated connections to remote nodes are properly terminated.

After unlinking the slot, it can be re-created again by re-using slot index.

Parameters

  • sender should point to an opened sender

  • slot specifies the sender slot

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

int roc_sender_write(roc_sender *sender, const roc_frame *frame)

Encode samples to packets and transmit them to the receiver.

Encodes samples to packets and enqueues them for transmission by the network worker thread of the context.

If ROC_CLOCK_SOURCE_INTERNAL is used, the function blocks until it’s time to transmit the samples according to the configured sample rate. The function returns after encoding and enqueuing the packets, without waiting when the packets are actually transmitted.

Until the sender is connected to at least one receiver, the stream is just dropped. If the sender is connected to multiple receivers, the stream is duplicated to each of them.

Parameters

  • sender should point to an opened sender

  • frame should point to an initialized frame; it should contain pointer to a buffer and it’s size; the buffer is fully copied into the sender

Returns

  • returns zero if all samples were successfully encoded and enqueued

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of frame; it may be safely deallocated after the function returns

int roc_sender_close(roc_sender *sender)

Close the sender.

Deinitializes and deallocates the sender, and detaches it from the context. The user should ensure that nobody uses the sender during and after this call. If this function fails, the sender is kept opened and attached to the context.

Parameters

  • sender should point to an opened sender

Returns

  • returns zero if the sender was successfully closed

  • returns a negative value if the arguments are invalid

Ownership

  • ends the user ownership of sender; it can’t be used anymore after the function returns

roc_receiver

#include <roc/receiver.h>
typedef struct roc_receiver roc_receiver

Receiver node.

Receiver gets the network packets from multiple senders, decodes audio streams from them, mixes multiple streams into a single stream, and returns it to the user.

Context

Receiver is automatically attached to a context when opened and detached from it when closed. The user should not close the context until the receiver is closed.

Receiver work consists of two parts: packet reception and stream decoding. The decoding part is performed in the receiver itself, and the reception part is performed in the context network worker threads.

Life cycle

  • A receiver is created using roc_receiver_open().

  • Optionally, the receiver parameters may be fine-tuned using roc_receiver_configure().

  • The receiver either binds local endpoints using roc_receiver_bind(), allowing senders connecting to them, or itself connects to remote sender endpoints using roc_receiver_connect(). What approach to use is up to the user.

  • The audio stream is iteratively read from the receiver using roc_receiver_read(). Receiver returns the mixed stream from all connected senders.

  • The receiver is destroyed using roc_receiver_close().

Slots, interfaces, and endpoints

Receiver has one or multiple slots, which may be independently bound or connected. Slots may be used to bind receiver to multiple addresses. Slots are numbered from zero and are created automatically. In simple cases just use ROC_SLOT_DEFAULT.

Each slot has its own set of interfaces, one per each type defined in roc_interface. The interface defines the type of the communication with the remote node and the set of the protocols supported by it.

Supported actions with the interface:

  • Call roc_receiver_bind() to bind the interface to a local roc_endpoint. In this case the receiver accepts connections from senders mixes their streams into the single output stream.

  • Call roc_receiver_connect() to connect the interface to a remote roc_endpoint. In this case the receiver initiates connection to the sender and requests it to start sending media stream to the receiver.

Supported interface configurations:

Slots can be removed using roc_receiver_unlink(). Removing a slot also removes all its interfaces and terminates all associated connections.

Slots can be added and removed at any time on fly and from any thread. It is safe to do it from another thread concurrently with reading frames. Operations with slots won’t block concurrent reads.

FEC scheme

If ROC_INTERFACE_CONSOLIDATED is used, it automatically creates all necessary transport interfaces and the user should not bother about them.

Otherwise, the user should manually configure ROC_INTERFACE_AUDIO_SOURCE and ROC_INTERFACE_AUDIO_REPAIR interfaces:

The protocols for the two interfaces should correspond to each other and to the FEC scheme. For example, if ROC_FEC_ENCODING_RS8M is used, the protocols should be ROC_PROTO_RTP_RS8M_SOURCE and ROC_PROTO_RS8M_REPAIR.

Sessions

Receiver creates a session object for every sender connected to it. Sessions can appear and disappear at any time. Multiple sessions can be active at the same time.

A session is identified by the sender address. A session may contain multiple packet streams sent to different receiver ports. If the sender employs FEC, the session will contain source and repair packet streams. Otherwise, the session will contain a single source packet stream.

A session is created automatically on the reception of the first packet from a new address and destroyed when there are no packets during a timeout. A session is also destroyed on other events like a large latency underrun or overrun or broken playback, but if the sender continues to send packets, it will be created again shortly.

Mixing

Receiver mixes audio streams from all currently active sessions into a single output stream.

The output stream continues no matter how much active sessions there are at the moment. In particular, if there are no sessions, the receiver produces a stream with all zeros.

Sessions can be added and removed from the output stream at any time, probably in the middle of a frame.

Sample rate

Every session may have a different sample rate. And even if nominally all of them are of the same rate, device frequencies usually differ by a few tens of Hertz.

Receiver compensates these differences by adjusting the rate of every session stream to the rate of the receiver output stream using a per-session resampler. The frequencies factor between the sender and the receiver clocks is calculated dynamically for every session based on the session incoming packet queue size.

Resampling is a quite time-consuming operation. The user can choose between several resampler profiles providing different compromises between CPU consumption and quality.

Clock source

Receiver should decode samples at a constant rate that is configured when the receiver is created. There are two ways to accomplish this:

  • If the user enabled internal clock (ROC_CLOCK_SOURCE_INTERNAL), the receiver employs a CPU timer to block reads until it’s time to decode the next bunch of samples according to the configured sample rate.

    This mode is useful when the user passes samples to a non-realtime destination, e.g. to an audio file.

  • If the user enabled external clock (ROC_CLOCK_SOURCE_EXTERNAL), the samples read from the receiver are decoded immediately and hence the user is responsible to call read operation according to the sample rate.

    This mode is useful when the user passes samples to a realtime destination with its own clock, e.g. to an audio device. Internal clock should not be used in this case because the audio device and the CPU might have slightly different clocks, and the difference will eventually lead to an underrun or an overrun.

Thread safety

Can be used concurrently.

int roc_receiver_open(roc_context *context, const roc_receiver_config *config, roc_receiver **result)

Open a new receiver.

Allocates and initializes a new receiver, and attaches it to the context.

Parameters

  • context should point to an opened context

  • config should point to an initialized config

  • result should point to an unitialized roc_receiver pointer

Returns

  • returns zero if the receiver was successfully created

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

  • passes the ownership of result to the user; the user is responsible to call roc_receiver_close() to free it

  • attaches created receiver to context; the user should not close context before closing receiver

int roc_receiver_configure(roc_receiver *receiver, roc_slot slot, roc_interface iface, const roc_interface_config *config)

Set receiver interface configuration.

Updates configuration of specified interface of specified slot. If called, the call should be done before calling roc_receiver_bind() or roc_receiver_connect() for the same interface.

Automatically initializes slot with given index if it’s used first time.

If an error happens during configure, the whole slot is disabled and marked broken. The slot index remains reserved. The user is responsible for removing the slot using roc_receiver_unlink(), after which slot index can be reused.

Parameters

  • receiver should point to an opened receiver

  • slot specifies the receiver slot

  • iface specifies the receiver interface

  • config should be point to an initialized config

Returns

  • returns zero if config was successfully updated

  • returns a negative value if the arguments are invalid

  • returns a negative value if slot is already bound or connected

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

int roc_receiver_bind(roc_receiver *receiver, roc_slot slot, roc_interface iface, roc_endpoint *endpoint)

Bind the receiver interface to a local endpoint.

Checks that the endpoint is valid and supported by the interface, allocates a new ingoing port, and binds it to the local endpoint.

Each slot’s interface can be bound or connected only once. May be called multiple times for different slots or interfaces.

Automatically initializes slot with given index if it’s used first time.

If an error happens during bind, the whole slot is disabled and marked broken. The slot index remains reserved. The user is responsible for removing the slot using roc_receiver_unlink(), after which slot index can be reused.

If endpoint has explicitly set zero port, the receiver is bound to a randomly chosen ephemeral port. If the function succeeds, the actual port to which the receiver was bound is written back to endpoint.

Parameters

  • receiver should point to an opened receiver

  • slot specifies the receiver slot

  • iface specifies the receiver interface

  • endpoint specifies the receiver endpoint

Returns

  • returns zero if the receiver was successfully bound to a port

  • returns a negative value if the arguments are invalid

  • returns a negative value if the address can’t be bound

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of endpoint; it may be safely deallocated after the function returns

int roc_receiver_query(roc_receiver *receiver, roc_slot slot, roc_receiver_metrics *metrics)

Query receiver slot metrics.

Reads receiver slot metrics into provided struct.

To retrieve per-session metrics, set sessions field of roc_receiver_metrics to a buffer of roc_session_metrics structs, and sessions_size to the number of structs in buffer. The function will write session metrcis to the buffer and update sessions_size with the actual number of sessions written.

If sessions_size is lesser than actual number of sessions, metrics for some sessions will be dropped. num_sessions will always contain actual total number.

If sessions field is NULL, per-session metrics are not retrieved.

Parameters

  • receiver should point to an opened receiver

  • slot specifies the receiver slot

  • metrics specifies struct where to write metrics

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

Ownership

  • doesn’t take or share the ownership of metrics or its sessions field; they may be safely deallocated after the function returns

Delete receiver slot.

Disconnects, unbinds, and removes all slot interfaces and removes the slot. All associated connections to remote nodes are properly terminated.

After unlinking the slot, it can be re-created again by re-using slot index.

Parameters

  • receiver should point to an opened receiver

  • slot specifies the receiver slot

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

int roc_receiver_read(roc_receiver *receiver, roc_frame *frame)

Read samples from the receiver.

Reads retrieved network packets, decodes packets, routes packets to sessions, repairs losses, extracts samples, adjusts sample rate and channel layout, compensates clock drift, mixes samples from all sessions, and finally stores samples into the provided frame.

If ROC_CLOCK_SOURCE_INTERNAL is used, the function blocks until it’s time to decode the samples according to the configured sample rate.

Until the receiver is connected to at least one sender, it produces silence. If the receiver is connected to multiple senders, it mixes their streams into one.

Parameters

  • receiver should point to an opened receiver

  • frame should point to an initialized frame; it should contain pointer to a buffer and it’s size; the buffer is fully filled with data from receiver

Returns

  • returns zero if all samples were successfully decoded

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of frame; it may be safely deallocated after the function returns

int roc_receiver_close(roc_receiver *receiver)

Close the receiver.

Deinitializes and deallocates the receiver, and detaches it from the context. The user should ensure that nobody uses the receiver during and after this call. If this function fails, the receiver is kept opened and attached to the context.

Parameters

  • receiver should point to an opened receiver

Returns

  • returns zero if the receiver was successfully closed

  • returns a negative value if the arguments are invalid

Ownership

  • ends the user ownership of receiver; it can’t be used anymore after the function returns

roc_sender_encoder

#include <roc/sender_encoder.h>
typedef struct roc_sender_encoder roc_sender_encoder

Sender encoder node.

Sender encoder gets an audio stream from the user, encodes it into network packets, and provides encoded packets back to the user.

Sender encoder is a simplified networkless version of roc_sender. It implements the same pipeline, but instead of sending packets, it just provides them to the user. The user is responsible for delivering these packets to receiver.

For detailed description of sender pipeline, see documentation for roc_sender.

Life cycle

  • Encoder is created using roc_sender_encoder_open().

  • The user activates one or more interfaces by invoking roc_sender_encoder_activate(). This tells encoder what types of streams to produces and what protocols to use for them (e.g. only audio packets or also redundancy packets).

  • The audio stream is iteratively pushed to the encoder using roc_sender_encoder_push(). The sender encodes the stream into packets and accumulates them in internal queue.

  • The packet stream is iteratively popped from the encoder internal queue using roc_sender_encoder_pop(). User should retrieve all available packets from all activated interfaces every time after pushing a frame.

  • User is responsible for delivering packets to roc_receiver_decoder and pushing them to appropriate interfaces of decoder.

  • The sender is eventually destroyed using roc_sender_encoder_close().

Interfaces and protocols

Sender encoder may have one or several interfaces, as defined in roc_interface. The interface defines the type of the communication with the remote node and the set of the protocols supported by it.

Each interface has its own packet queue. When a frame is pushed to the encoder, it may produce multiple packets for each interface queue. The user then should pop packets from each interface that was activated.

Thread safety

Can be used concurrently.

int roc_sender_encoder_open(roc_context *context, const roc_sender_config *config, roc_sender_encoder **result)

Open a new encoder.

Allocates and initializes a new encoder, and attaches it to the context.

Parameters

  • context should point to an opened context

  • config should point to an initialized config

  • result should point to an unitialized roc_sender_encoder pointer

Returns

  • returns zero if the encoder was successfully created

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

  • passes the ownership of result to the user; the user is responsible to call roc_sender_encoder_close() to free it

  • attaches created encoder to context; the user should not close context before closing encoder

int roc_sender_encoder_activate(roc_sender_encoder *encoder, roc_interface iface, roc_protocol proto)

Activate encoder interface.

Checks that the protocol is valid and supported by the interface, and initializes given interface with given protocol.

The user should invoke roc_sender_encoder_pop() for all activated interfaces and deliver packets to appropriate interfaces of roc_receiver_decoder.

Parameters

  • encoder should point to an opened encoder

  • iface specifies the encoder interface

  • proto specifies the encoder protocol

Returns

  • returns zero if interface was successfully activated

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

int roc_sender_encoder_query(roc_sender_encoder *encoder, roc_sender_metrics *metrics)

Query encoder metrics.

Reads encoder metrics into provided struct.

Parameters

  • encoder should point to an opened encoder

  • metrics specifies struct where to write metrics

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

Ownership

  • doesn’t take or share the ownership of metrics; it may be safely deallocated after the function returns

int roc_sender_encoder_push(roc_sender_encoder *encoder, const roc_frame *frame)

Write frame to encoder.

Encodes samples to into network packets and enqueues them to internal queues of activated interfaces.

If ROC_CLOCK_SOURCE_INTERNAL is used, the function blocks until it’s time to encode the samples according to the configured sample rate.

Until at least one interface is activated, the stream is just dropped.

Parameters

  • encoder should point to an opened encoder

  • frame should point to an initialized frame; it should contain pointer to a buffer and it’s size; the buffer is fully copied into encoder

Returns

  • returns zero if all samples were successfully encoded and enqueued

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of frame; it may be safely deallocated after the function returns

int roc_sender_encoder_pop(roc_sender_encoder *encoder, roc_interface iface, roc_packet *packet)

Read packet from encoder.

Removes encoded packet from interface queue and returns it to the user.

Packets are added to the queue from roc_sender_encoder_push(). Each push may produce multiple packets, so the user should iteratively pop packets until error. This should be repeated for all activated interfaces.

Parameters

  • encoder should point to an opened encoder

  • packet should point to an initialized packet; it should contain pointer to a buffer and it’s size; packet bytes are copied to user’s buffer and the size field is updated with the actual packet size

Returns

  • returns zero if a packet was successfully copied from encoder

  • returns a negative value if there are no more packets for this interface

  • returns a negative value if the interface is not activated

  • returns a negative value if the buffer size of the provided packet is too small

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of packet; it may be safely deallocated after the function returns

int roc_sender_encoder_close(roc_sender_encoder *encoder)

Close encoder.

Deinitializes and deallocates the encoder, and detaches it from the context. The user should ensure that nobody uses the encoder during and after this call. If this function fails, the encoder is kept opened and attached to the context.

Parameters

  • encoder should point to an opened encoder

Returns

  • returns zero if the encoder was successfully closed

  • returns a negative value if the arguments are invalid

Ownership

  • ends the user ownership of encoder; it can’t be used anymore after the function returns

roc_receiver_decoder

#include <roc/receiver_decoder.h>
typedef struct roc_receiver_decoder roc_receiver_decoder

Receiver decoder node.

Receiver decoder gets an encoded network packets from the user, decodes audio stream from them, and provides it back to the user.

Receiver decoder is a simplified networkless version of roc_receiver. It implements the same pipeline, but instead of receiving packets, it just gets them from the user. The user is responsible for delivering these packets to receiver.

For detailed description of receiver pipeline, see documentation for roc_receiver.

Life cycle

Interfaces and protocols

Receiver decoder may have one or several interfaces, as defined in roc_interface. The interface defines the type of the communication with the remote node and the set of the protocols supported by it.

Each interface has its own packet queue. When a packet is pushed to the decoder, it is accumulated in the queue. When a frame is popped from the decoder, it consumes those accumulated packets.

Thread safety

Can be used concurrently.

int roc_receiver_decoder_open(roc_context *context, const roc_receiver_config *config, roc_receiver_decoder **result)

Open a new decoder.

Allocates and initializes a new decoder, and attaches it to the context.

Parameters

  • context should point to an opened context

  • config should point to an initialized config

  • result should point to an unitialized roc_receiver_decoder pointer

Returns

  • returns zero if the decoder was successfully created

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of config; it may be safely deallocated after the function returns

  • passes the ownership of result to the user; the user is responsible to call roc_receiver_decoder_close() to free it

  • attaches created decoder to context; the user should not close context before closing decoder

int roc_receiver_decoder_activate(roc_receiver_decoder *decoder, roc_interface iface, roc_protocol proto)

Activate decoder interface.

Checks that the protocol is valid and supported by the interface, and initializes given interface with given protocol.

The user should invoke roc_receiver_decoder_push() for all activated interfaces and deliver packets from appropriate interfaces of roc_sender_encoder.

Parameters

  • decoder should point to an opened decoder

  • iface specifies the decoder interface

  • proto specifies the decoder protocol

Returns

  • returns zero if interface was successfully activated

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

int roc_receiver_decoder_query(roc_receiver_decoder *decoder, roc_receiver_metrics *metrics)

Query decoder metrics.

Reads decoder metrics into provided struct.

To retrieve per-session metrics, set sessions field of roc_receiver_metrics to a buffer of roc_session_metrics structs, and sessions_size to the number of structs in buffer. The function will write session metrcis to the buffer and update sessions_size with the actual number of sessions written.

If sessions_size is lesser than actual number of sessions, metrics for some sessions will be dropped. num_sessions will always contain actual total number.

If sessions field is NULL, per-session metrics are not retrieved.

Parameters

  • decoder should point to an opened decoder

  • metrics specifies struct where to write metrics

Returns

  • returns zero if the slot was successfully removed

  • returns a negative value if the arguments are invalid

  • returns a negative value if the slot does not exist

Ownership

  • doesn’t take or share the ownership of metrics or its sessions field; they may be safely deallocated after the function returns

int roc_receiver_decoder_push(roc_receiver_decoder *decoder, roc_interface iface, const roc_packet *packet)

Write packet to decoder.

Add encoded packet to the interface queue.

The user should iteratively push all delivered packets to appropriate interfaces. They will be later consumed by roc_receiver_decoder_pop().

Parameters

  • decoder should point to an opened decoder

  • packet should point to an initialized packet; it should contain pointer to a buffer and it’s size; the buffer is fully copied into decoder

Returns

  • returns zero if a packet was successfully copied to decoder

  • returns a negative value if the interface is not activated

  • returns a negative value if the buffer size of the provided packet is too large

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of packet; it may be safely deallocated after the function returns

int roc_receiver_decoder_pop(roc_receiver_decoder *decoder, roc_frame *frame)

Read samples from decoder.

Reads pushed network packets, decodes packets, repairs losses, extracts samples, adjusts sample rate and channel layout, compensates clock drift, and stores samples into the provided frame.

If ROC_CLOCK_SOURCE_INTERNAL is used, the function blocks until it’s time to decode the samples according to the configured sample rate.

Until at least one interface is activated, decoder produces silence.

Parameters

  • decoder should point to an opened decoder

  • frame should point to an initialized frame; it should contain pointer to a buffer and it’s size; the buffer is fully filled with data from decoder

Returns

  • returns zero if all samples were successfully decoded

  • returns a negative value if the arguments are invalid

  • returns a negative value on resource allocation failure

Ownership

  • doesn’t take or share the ownership of frame; it may be safely deallocated after the function returns

int roc_receiver_decoder_close(roc_receiver_decoder *decoder)

Close decoder.

Deinitializes and deallocates the decoder, and detaches it from the context. The user should ensure that nobody uses the decoder during and after this call. If this function fails, the decoder is kept opened and attached to the context.

Parameters

  • decoder should point to an opened decoder

Returns

  • returns zero if the decoder was successfully closed

  • returns a negative value if the arguments are invalid

Ownership

  • ends the user ownership of decoder; it can’t be used anymore after the function returns

roc_frame

#include <roc/frame.h>
struct roc_frame

Audio frame.

Represents a multichannel sequence of audio samples. The user is responsible for allocating and deallocating the frame and the data it is pointing to.

Thread safety

Should not be used concurrently.

Public Members

void *samples

Audio samples.

Sample rate, channel set, and encoding are defined by the sender or receiver parameters.

size_t samples_size

Sample buffer size.

Defines the size of samples buffer in bytes.

roc_packet

#include <roc/packet.h>
struct roc_packet

Network packet.

Represents opaque encoded binary packet.

Thread safety

Should not be used concurrently.

Public Members

void *bytes

Packet bytes.

size_t bytes_size

Packet bytes count.

roc_endpoint

#include <roc/endpoint.h>
typedef struct roc_endpoint roc_endpoint

Network endpoint.

Endpoint is a network entry point of a node. The definition includes the protocol being used, network host and port, and, for some protocols, a resource. All these parts together are unambiguously represented by a URI. The user may set or get the entire URI or its individual parts.

Endpoint URI

Endpoint URI syntax is a subset of the syntax defined in RFC 3986:

protocol://host[:port][/path][?query]
Examples:
  • rtsp://localhost:123/path?query

  • rtp+rs8m://localhost:123

  • rtp://127.0.0.1:123

  • rtp://[::1]:123

The following protocols (schemes) are supported:

The host field should be either FQDN (domain name), or IPv4 address, or IPv6 address in square brackets.

The port field can be omitted if the protocol defines standard port. Otherwise, the port can not be omitted. For example, RTSP defines standard port, but RTP doesn’t.

The path and query fields are allowed only for protocols that support them. For example, they’re supported by RTSP, but not by RTP.

Field invalidation

If some field is attempted to be set to an invalid value (for example, an invalid port number), this specific field is marked as invalid until it is successfully set to some valid value.

Sender and receiver refuse to bind or connect an endpoint which has invalid fields or doesn’t have some mandatory fields. Hence, it is safe to ignore errors returned by endpoint setters and check only for errors returned by bind and connect operations.

Thread safety

Should not be used concurrently.

int roc_endpoint_allocate(roc_endpoint **result)

Allocate and initialize endpoint.

All components of the newly created endpoint are empty.

Parameters

  • result should point to an unitialized roc_endpoint pointer

Returns

  • returns zero if endpoint was successfully allocated and initialized

  • returns a negative value on invalid arguments

  • returns a negative value on allocation failure

Ownership

int roc_endpoint_set_uri(roc_endpoint *endpoint, const char *uri)

Set endpoint URI.

Parses and sets endpoint URI. Overrides or clears each URI component.

On failure, invalidates endpoint URI. The endpoint becomes invalid until its URI or every individual component is successfully set.

Parameters

  • endpoint should point to initialized endpoint

  • uri should be a valid endpoint URI

Returns

  • returns zero if URI was successfully parsed and set

  • returns a negative value on invalid arguments

  • returns a negative value on allocation failure

Ownership

  • doesn’t take or share the ownership of uri; it may be safely deallocated after the function returns

int roc_endpoint_set_protocol(roc_endpoint *endpoint, roc_protocol proto)

Set endpoint protocol (scheme).

On failure, invalidates endpoint protocol. The endpoint becomes invalid until its protocol is successfully set.

Parameters

  • endpoint should point to initialized endpoint

  • proto defines new protocol

Returns

  • returns zero if protocol was successfully set

  • returns a negative value on invalid arguments

  • returns a negative value if protocol is incompatible with other URI parameters

int roc_endpoint_set_host(roc_endpoint *endpoint, const char *host)

Set endpoint host.

On failure, invalidates endpoint host. The endpoint becomes invalid until its host is successfully set.

Parameters

  • endpoint should point to initialized endpoint

  • host specifies FQDN, IPv4 address, or IPv6 address

Returns

  • returns zero if host was successfully set

  • returns a negative value on invalid arguments

  • returns a negative value on allocation failure

Ownership

  • doesn’t take or share the ownership of host; it may be safely deallocated after the function returns

int roc_endpoint_set_port(roc_endpoint *endpoint, int port)

Set endpoint port.

When binding an endpoint, the port may be set to zero to select a random port. The selected port will be then written back to the endpoint. When connecting an endpoint, the port should be positive.

If port is not set, the standard port for endpoint protocol is used. This is allowed only if the protocol defines its standard port.

If port is already set, it can be unset by setting to special value “-1”.

On failure, invalidates endpoint port. The endpoint becomes invalid until its port is successfully set.

Parameters

  • endpoint should point to initialized endpoint

  • port specifies UDP or TCP port in range [0; 65535]

Returns

  • returns zero if port was successfully set

  • returns a negative value on invalid arguments

int roc_endpoint_set_resource(roc_endpoint *endpoint, const char *encoded_resource)

Set endpoint resource (path and query).

Path and query are both optional. Any of them may be omitted. If path is present, it should be absolute.

The given resource should be percent-encoded by user if it contains special characters. It may be inserted into the URI as is.

If resource is already set, it can be unset by setting to NULL or “”.

On failure, invalidates endpoint resource. The endpoint becomes invalid until its resource is successfully set.

Parameters

  • endpoint should point to initialized endpoint

  • encoded_resource specifies percent-encoded path and query

Returns

  • returns zero if resource was successfully set

  • returns a negative value on invalid arguments

  • returns a negative value on allocation failure

Ownership

  • doesn’t take or share the ownership of encoded_resource; it may be safely deallocated after the function returns

int roc_endpoint_get_uri(const roc_endpoint *endpoint, char *buf, size_t *bufsz)

Get endpoint URI.

Formats endpoint URI to user-provided buffer.

If the function succeeds, the output string is zero-terminated. No matter whether the function succeeds or fails, bufsz is updated with the actual output string length, including terminating zero byte. buf may be NULL; in this case nothing is written, but bufsz is still updated. This can be used to determine the proper buffer size in before.

Parameters

  • endpoint should point to initialized endpoint

  • buf should point to a buffer of bufsz bytes

  • bufsz defines the buffer size

Returns

  • returns zero if URI was successfully formatted

  • returns a negative value on invalid arguments

  • returns a negative value if endpoint URI is not set

  • returns a negative value if buffer is too small

int roc_endpoint_get_protocol(const roc_endpoint *endpoint, roc_protocol *proto)

Get endpoint protocol (scheme).

Parameters

  • endpoint should point to initialized endpoint

  • proto should point to a variable where to write the protocol

Returns

  • returns zero if protocol was successfully written

  • returns a negative value if endpoint protocol is not set

  • returns a negative value on invalid arguments

int roc_endpoint_get_host(const roc_endpoint *endpoint, char *buf, size_t *bufsz)

Get endpoint host.

Formats endpoint URI host to user-provided buffer.

If the function succeeds, the output string is zero-terminated. No matter whether the function succeeds or fails, bufsz is updated with the actual output string length, including terminating zero byte. buf may be NULL; in this case nothing is written, but bufsz is still updated. This can be used to determine the proper buffer size in before.

Parameters

  • endpoint should point to initialized endpoint

  • buf should point to a buffer of bufsz bytes

  • bufsz defines the buffer size

Returns

  • returns zero if host was successfully formatted

  • returns a negative value if endpoint host is not set

  • returns a negative value on invalid arguments

  • returns a negative value if buffer is too small

int roc_endpoint_get_port(const roc_endpoint *endpoint, int *port)

Get endpoint port.

Parameters

  • endpoint should point to initialized endpoint

  • port should point to a variable where to write the port

Returns

  • returns zero if port was successfully written

  • returns a negative value if endpoint port is not set

  • returns a negative value on invalid arguments

int roc_endpoint_get_resource(const roc_endpoint *endpoint, char *buf, size_t *bufsz)

Get endpoint resource (path and query).

Formats endpoint URI resource to user-provided buffer. The written resource is percent-encoded.

If the function succeeds, the output string is zero-terminated. No matter whether the function succeeds or fails, bufsz is updated with the actual output string length, including terminating zero byte. buf may be NULL; in this case nothing is written, but bufsz is still updated. This can be used to determine the proper buffer size in before.

Parameters

  • endpoint should point to initialized endpoint

  • buf should point to a buffer of bufsz bytes

  • bufsz defines the buffer size

Returns

  • returns zero if resource was successfully formatted

  • returns a negative value if neither of endpoint path and query is set

  • returns a negative value on invalid arguments

  • returns a negative value if buffer is too small

int roc_endpoint_deallocate(roc_endpoint *endpoint)

Deinitialize and deallocate endpoint.

Parameters

  • endpoint should point to initialized endpoint

Returns

  • returns zero if endpoint was successfully deallocated

  • returns a negative value on invalid arguments

Ownership

  • ends the user ownership of endpoint; it can’t be used anymore after the function returns

roc_config

#include <roc/config.h>
typedef unsigned long long roc_slot

Network slot.

A node (sender or receiver) may have multiple slots, which may be independently bound or connected. You can use multiple slots on sender to connect it to multiple receiver addresses, and you can use multiple slots on receiver to bind it to multiple receiver addresses.

Slots are numbered from zero and are created implicitly. Just specify slot index when binding or connecting endpoint, and slot will be automatically created if it was not created yet. Numbers does not need to be continuous and can be arbitrary.

In simple cases, when one slot is enough, just use ROC_SLOT_DEFAULT.

Inside each slot, there can be up to one endpoint for each interface type. See roc_interface for details.

static const roc_slot ROC_SLOT_DEFAULT = 0

Alias for the slot with index zero.

Has no special meaning, exists just for convenience.

See also

roc_slot

enum roc_interface

Network interface.

Interface is a way to access the node (sender or receiver) via network.

Each node slot has multiple interfaces, one of each type. The user interconnects nodes by binding one of the first node’s interfaces to an URI and then connecting the corresponding second node’s interface to that URI.

A URI is represented by roc_endpoint object.

The interface defines the type of the communication with the remote node and the set of protocols (URI schemes) that can be used with this particular interface.

ROC_INTERFACE_CONSOLIDATED is an interface for high-level protocols which automatically manage all necessary communication: transport streams, control messages, parameter negotiation, etc. When a consolidated connection is established, nodes may automatically setup lower-level interfaces like ROC_INTERFACE_AUDIO_SOURCE, ROC_INTERFACE_AUDIO_REPAIR, and ROC_INTERFACE_AUDIO_CONTROL.

ROC_INTERFACE_CONSOLIDATED is mutually exclusive with lower-level interfaces. In most cases, the user needs only ROC_INTERFACE_CONSOLIDATED. However, the lower-level interfaces may be useful if an external signaling mechanism is used or for compatibility with third-party software.

ROC_INTERFACE_AUDIO_SOURCE and ROC_INTERFACE_AUDIO_REPAIR are lower-level unidirectional transport-only interfaces. The first is used to transmit audio stream, and the second is used to transmit redundant repair stream, if FEC is enabled.

ROC_INTERFACE_AUDIO_CONTROL is a lower-level interface for control streams. If you use ROC_INTERFACE_AUDIO_SOURCE and ROC_INTERFACE_AUDIO_REPAIR, you usually also need to use ROC_INTERFACE_AUDIO_CONTROL to enable carrying additional non-transport information.

Values:

enumerator ROC_INTERFACE_CONSOLIDATED

Interface that consolidates all types of streams (source, repair, control).

Allowed operations:

  • bind (sender, receiver)

  • connect (sender, receiver)

Allowed protocols:

enumerator ROC_INTERFACE_AUDIO_SOURCE

Interface for audio stream source data.

Allowed operations:

  • bind (receiver)

  • connect (sender)

Allowed protocols:

enumerator ROC_INTERFACE_AUDIO_REPAIR

Interface for audio stream repair data.

Allowed operations:

  • bind (receiver)

  • connect (sender)

Allowed protocols:

enumerator ROC_INTERFACE_AUDIO_CONTROL

Interface for audio control messages.

Allowed operations:

  • bind (sender, receiver)

  • connect (sender, receiver)

Allowed protocols:

enum roc_protocol

Network protocol.

Defines URI scheme of roc_endpoint.

Values:

enumerator ROC_PROTO_RTSP

RTSP 1.0 (RFC 2326) or RTSP 2.0 (RFC 7826).

Interfaces:

Transports:

  • for signaling: TCP

  • for media: RTP and RTCP over UDP or TCP

enumerator ROC_PROTO_RTP

RTP over UDP (RFC 3550).

Interfaces:

Transports:

  • UDP

Audio encodings:

FEC encodings:

  • none

enumerator ROC_PROTO_RTP_RS8M_SOURCE

RTP source packet (RFC 3550) + FECFRAME Reed-Solomon footer (RFC 6865) with m=8.

Interfaces:

Transports:

  • UDP

Audio encodings:

FEC encodings:

enumerator ROC_PROTO_RS8M_REPAIR

FEC repair packet + FECFRAME Reed-Solomon header (RFC 6865) with m=8.

Interfaces:

Transports:

  • UDP

FEC encodings:

enumerator ROC_PROTO_RTP_LDPC_SOURCE

RTP source packet (RFC 3550) + FECFRAME LDPC-Staircase footer (RFC 6816).

Interfaces:

Transports:

  • UDP

Audio encodings:

FEC encodings:

enumerator ROC_PROTO_LDPC_REPAIR

FEC repair packet + FECFRAME LDPC-Staircase header (RFC 6816).

Interfaces:

Transports:

  • UDP

FEC encodings:

enumerator ROC_PROTO_RTCP

RTCP over UDP (RFC 3550).

Interfaces:

Transports:

  • UDP

enum roc_packet_encoding

Packet encoding.

Each packet encoding defines sample format, channel layout, and rate. Each packet encoding is caompatible with specific protocols.

Values:

enumerator ROC_PACKET_ENCODING_AVP_L16_MONO

PCM signed 16-bit, 1 channel, 44100 rate.

Represents 1-channel L16 stereo encoding from RTP A/V Profile (RFC 3551). Uses uncompressed samples coded as interleaved 16-bit signed big-endian integers in two’s complement notation.

Supported by protocols:

enumerator ROC_PACKET_ENCODING_AVP_L16_STEREO

PCM signed 16-bit, 2 channels, 44100 rate.

Represents 2-channel L16 stereo encoding from RTP A/V Profile (RFC 3551). Uses uncompressed samples coded as interleaved 16-bit signed big-endian integers in two’s complement notation.

Supported by protocols:

enum roc_fec_encoding

Forward Error Correction encoding.

Each FEC encoding is caompatible with specific protocols.

Values:

enumerator ROC_FEC_ENCODING_DISABLE

No FEC encoding.

Compatible with ROC_PROTO_RTP protocol.

Pros:

  • compatible with third-party software that does not support FECFRAME

Cons:

  • no packet recovery

enumerator ROC_FEC_ENCODING_DEFAULT

Default FEC encoding.

Current default is ROC_FEC_ENCODING_RS8M.

enumerator ROC_FEC_ENCODING_RS8M

Reed-Solomon FEC encoding (RFC 6865) with m=8.

Good for small block sizes (below 256 packets). Compatible with ROC_PROTO_RTP_RS8M_SOURCE and ROC_PROTO_RS8M_REPAIR protocols for source and repair endpoints.

Pros:

  • good repair capabilities even on small block sizes

Cons:

  • high CPU usage on large block sizes

enumerator ROC_FEC_ENCODING_LDPC_STAIRCASE

LDPC-Staircase FEC encoding (RFC 6816).

Good for large block sizes (above 1024 packets). Compatible with ROC_PROTO_RTP_LDPC_SOURCE and ROC_PROTO_LDPC_REPAIR protocols for source and repair endpoints.

Pros:

  • low CPU usage even on large block sizes

Cons:

  • low repair capabilities on small block sizes

enum roc_format

Sample format.

Defines how each sample is represented. Does not define channels layout and sample rate.

Values:

enumerator ROC_FORMAT_PCM_FLOAT32

PCM floats.

Uncompressed samples coded as 32-bit native-endian floats in range [-1; 1]. Channels are interleaved, e.g. two channels are encoded as “L R L R …”.

enum roc_channel_layout

Channel layout.

Defines number of channels and meaning of each channel.

Values:

enumerator ROC_CHANNEL_LAYOUT_MULTITRACK

Multi-track audio.

In multitrack layout, stream contains multiple channels which represent independent “tracks” without any special meaning (unlike stereo or surround) and hence without any special processing or mapping.

The number of channels is arbitrary and is defined by tracks field of roc_media_encoding struct.

enumerator ROC_CHANNEL_LAYOUT_MONO

Mono.

One channel with monophonic sound.

enumerator ROC_CHANNEL_LAYOUT_STEREO

Stereo.

Two channels: left, right.

struct roc_media_encoding

Media encoding.

Defines format and parameters of samples encoded in frames or packets.

Public Members

unsigned int rate

Sample frequency.

Defines number of samples per channel per second (e.g. 44100).

roc_format format

Sample format.

Defines sample precision and encoding.

roc_channel_layout channels

Channel layout.

Defines number of channels and meaning of each channel.

unsigned int tracks

Multi-track channel count.

If channels is ROC_CHANNEL_LAYOUT_MULTITRACK, defines number of channels (which represent independent “tracks”). For other channel layouts should be zero.

Should be in range [1; 1024].

enum roc_clock_source

Clock source for sender or receiver.

Defines wo is responsible to invoke read or write in proper time.

Values:

enumerator ROC_CLOCK_SOURCE_EXTERNAL

Sender or receiver is clocked by external user-defined clock.

Write and read operations are non-blocking. The user is responsible to call them in time, according to the external clock.

Use when samples source (from where you read them to pass to receiver) or destination (to where you write them after obtaining from sender) is active and has its own clock, e.g. it is a sound card.

enumerator ROC_CLOCK_SOURCE_INTERNAL

Sender or receiver is clocked by an internal pipeline clock.

Write and read operations are blocking. They automatically wait until it’s time to process the next bunch of samples according to the configured sample rate, based on a CPU timer.

Use when samples source (from where you read them to pass to receiver) or destination (to where you write them after obtaining from sender) is passive and does now have clock, e.g. it is a file on disk.

enum roc_clock_sync_backend

Clock synchronization algorithm.

Defines how sender and receiver clocks are synchronized.

Values:

enumerator ROC_CLOCK_SYNC_BACKEND_DISABLE

Disable clock synchronization.

In this mode, sender and receiver clocks are not synchronized. This mode is generally not recommended, since clock drift will lead to periodic playback disruptions caused by underruns and overruns.

enumerator ROC_CLOCK_SYNC_BACKEND_DEFAULT

Default backend.

Current default is ROC_CLOCK_SYNC_BACKEND_NIQ.

enumerator ROC_CLOCK_SYNC_BACKEND_NIQ

Clock synchronization based on network incoming queue size.

In this mode, receiver monitors incoming queue size and adjusts playback clock speed to match the estimated capture clock speed.

Pros:

  • works with any protocol (does not require RTCP or NTP)

Cons:

  • synchronizes only clock speed, but not position; different receivers will have different (constant) delays

  • affected by network jitter; spikes in packet delivery will cause slow oscillations in clock speed

enum roc_clock_sync_profile

Clock synchronization profile.

Defines what latency and jitter are tolerated by clock synchronization algorithm.

Values:

enumerator ROC_CLOCK_SYNC_PROFILE_DEFAULT

Default profile.

When ROC_CLOCK_SYNC_BACKEND_NIQ is used, selects ROC_CLOCK_SYNC_PROFILE_RESPONSIVE if target latency is low, and ROC_CLOCK_SYNC_PROFILE_GRADUAL if target latency is high.

enumerator ROC_CLOCK_SYNC_PROFILE_RESPONSIVE

Responsive clock adjustment.

Clock speed is adjusted quickly and accurately.

Requires high precision clock adjustment, hence recommended for use with ROC_RESAMPLER_BACKEND_BUILTIN.

Pros:

  • allows very low latency or synchronization error

Cons:

enumerator ROC_CLOCK_SYNC_PROFILE_GRADUAL

Gradual clock adjustment.

Clock speed is adjusted slowly and smoothly.

Pros:

  • works well even with high network jitter

  • works well with any resampler backend

Cons:

  • does not allow very low latency or synchronization error

enum roc_resampler_backend

Resampler backend.

Affects CPU usage, quality, and clock synchronization precision. Some backends may be disabled at build time.

Values:

enumerator ROC_RESAMPLER_BACKEND_DEFAULT

Default backend.

Selects ROC_RESAMPLER_BACKEND_BUILTIN when using ROC_CLOCK_SYNC_PROFILE_RESPONSIVE, or when SpeexDSP is disabled.

Otherwise, selects ROC_RESAMPLER_BACKEND_SPEEX.

enumerator ROC_RESAMPLER_BACKEND_BUILTIN

CPU-intensive good-quality high-precision built-in resampler.

This backend controls clock speed with very high precision, and hence is useful when latency or synchronization error should be very low.

This backend has higher CPU usage, especially on high resampling quality and on CPUs with small L3 caches.

The implementation is based on bandlimited interpolation algorithm.

This backend is always available.

Recommended for ROC_CLOCK_SYNC_PROFILE_RESPONSIVE and on good CPUs.

enumerator ROC_RESAMPLER_BACKEND_SPEEX

Fast good-quality low-precision resampler based on SpeexDSP.

This backend has low CPU usage even on high resampler quality and cheap CPUs.

This backend controls clock speed with lower precision, and is not so good when latency or synchronization error should be very low.

This backend is available only when SpeexDSP was enabled at build time.

Recommended for ROC_CLOCK_SYNC_PROFILE_GRADUAL and on cheap CPUs.

enumerator ROC_RESAMPLER_BACKEND_SPEEXDEC

Fast medium-quality and medium-precision resampler combining SpeexDSP with decimation.

This backend uses SpeexDSP for converting between base rates (e.g. 44100 vs 48000) and decimation/expansion (dropping or duplicating samples) for clock drift compensation.

Typical decimation rate needed to compensate clock drift is below 0.5ms/second (20 samples/second on 48Khz), which gives tolerable quality despite usage of decimation, especially for speech.

When frame and packet sample rates are equal (e.g. both are 44100), only decimation stage is needed, and this becomes fastest possible backend working almost as fast as memcpy().

When frame and packet rates are different, usage of this backend compared to ROC_RESAMPLER_BACKEND_SPEEX allows to sacrify some quality, but somewhat improve scaling precision and CPU usage in return.

This backend is available only when SpeexDSP was enabled at build time.

Recommended when CPU resources are extremely limited.

enum roc_resampler_profile

Resampler profile.

Affects CPU usage and quality. Each resampler backend treats profile in its own way.

Values:

enumerator ROC_RESAMPLER_PROFILE_DEFAULT

Default profile.

Current default is ROC_RESAMPLER_PROFILE_MEDIUM.

enumerator ROC_RESAMPLER_PROFILE_HIGH

High quality, higher CPU usage.

enumerator ROC_RESAMPLER_PROFILE_MEDIUM

Medium quality, medium CPU usage.

enumerator ROC_RESAMPLER_PROFILE_LOW

Low quality, lower CPU usage.

struct roc_context_config

Context configuration.

It is safe to memset() this struct with zeros to get a default config. It is also safe to memcpy() this struct to get a copy of config.

See also

roc_context

Public Members

unsigned int max_packet_size

Maximum size in bytes of a network packet.

Defines the amount of bytes allocated per network packet. Sender and receiver won’t handle packets larger than this. If zero, default value is used.

unsigned int max_frame_size

Maximum size in bytes of an audio frame.

Defines the amount of bytes allocated per intermediate internal frame in the pipeline. Does not limit the size of the frames provided by user. If zero, default value is used.

struct roc_sender_config

Sender configuration.

For most fields, zero value means “use default”, and you can memset() this struct with zeros and then set only a few fields that don’t have defaults. It is safe to use memcpy() to get a copy of config, the struct is flat.

See also

roc_sender

Public Members

roc_media_encoding frame_encoding

The encoding used in frames passed to sender.

Frame encoding defines sample format, channel layout, and sample rate in local frames created by user and passed to sender. Should be set (zero value is invalid).

roc_packet_encoding packet_encoding

The encoding used for packets produced by sender.

Packet encoding defines sample format, channel layout, and sample rate in network packets. If packet encoding differs from frame encoding, conversion is performed automatically.

If zero, sender selects packet encoding automatically based on frame_encoding. This automatic selection matches only encodings that have exact same sample rate and channel layout, and hence don’t require conversions. If you need conversions, you should set packet encoding explicitly.

If you want to force specific packet encoding, and built-in set of encodings is not enough, you can use roc_context_register_encoding() to register custom encoding, set packet_encoding to registered identifier. If you use signaling protocol like RTSP, it’s enough to register in just on sender; otherwise, you need to do the same on receiver as well.

unsigned long long packet_length

The length of the packets produced by sender, in nanoseconds.

Number of nanoseconds encoded per packet. The samples written to the sender are buffered until the full packet is accumulated or the sender is flushed or closed. Larger number reduces packet overhead but also increases latency. If zero, default value is used.

unsigned int packet_interleaving

Enable packet interleaving.

If non-zero, the sender shuffles packets before sending them. This may increase robustness but also increases latency.

roc_fec_encoding fec_encoding

FEC encoding to use.

If non-zero, the sender employs a FEC encoding to generate redundant packets which may be used on receiver to restore lost packets. This requires both sender and receiver to use two separate source and repair endpoints.

unsigned int fec_block_source_packets

Number of source packets per FEC block.

Used if some FEC encoding is selected.

Sender divides stream into blocks of N source (media) packets, and adds M repair (redundancy) packets to each block, where N is fec_block_source_packets and M is fec_block_repair_packets.

Larger number of source packets in block increases robustness (repair ratio), but also increases latency.

If zero, default value is used.

unsigned int fec_block_repair_packets

Number of repair packets per FEC block.

Used if some FEC encoding is selected.

Sender divides stream into blocks of N source (media) packets, and adds M repair (redundancy) packets to each block, where N is fec_block_source_packets and M is fec_block_repair_packets.

Larger number of repair packets in block increases robustness (repair ratio), but also increases traffic. Number of repair packets usually should be 1/2 or 2/3 of the number of source packets.

If zero, default value is used.

roc_clock_source clock_source

Clock source to use.

Defines whether write operation will be blocking or non-blocking. If zero, default value is used (ROC_CLOCK_SOURCE_EXTERNAL).

roc_resampler_backend resampler_backend

Resampler backend to use.

If zero, default value is used.

roc_resampler_profile resampler_profile

Resampler profile to use.

If non-zero, the sender employs resampler if the frame sample rate differs from the packet sample rate.

struct roc_receiver_config

Receiver configuration.

For most fields, zero value means “use default”, and you can memset() this struct with zeros and then set only a few fields that don’t have defaults. It is safe to use memcpy() to get a copy of config, the struct is flat.

See also

roc_receiver

Public Members

roc_media_encoding frame_encoding

The encoding used in frames returned by receiver.

Frame encoding defines sample format, channel layout, and sample rate in local frames returned by receiver to user. Should be set (zero value is invalid).

roc_clock_source clock_source

Clock source.

Defines whether read operation will be blocking or non-blocking. If zero, ROC_CLOCK_SOURCE_EXTERNAL is used.

roc_clock_sync_backend clock_sync_backend

Clock synchronization backend.

Defines how sender and receiver clocks are synchronized. If zero, default value is used.

roc_clock_sync_profile clock_sync_profile

Clock synchronization profile.

Defines what latency and network jitter are tolerated. If zero, default value is used.

roc_resampler_backend resampler_backend

Resampler backend.

Affects CPU usage, quality, and clock synchronization precision. If zero, default value is used.

roc_resampler_profile resampler_profile

Resampler profile.

Affects CPU usage and quality. If zero, default value is used.

unsigned long long target_latency

Target latency, in nanoseconds.

The session will not start playing until it accumulates the requested latency. Then, if clock synchronization is enabled, the session will adjust its clock to keep actual latency as close as possible to the target latency. If zero, default value is used.

unsigned long long latency_tolerance

Maximum allowed delta between current and target latency, in nanoseconds.

If session latency differs from the target latency by more than given value, the session is terminated (it can then automatically restart). Receiver itself is not terminated; if there are no sessions, it will produce zeros. If zero, default value is used.

long long no_playback_timeout

Timeout for the lack of playback, in nanoseconds.

If there is no playback during this period, the session is terminated (it can then automatically restart). Receiver itself is not terminated; if there are no sessions, it will produce zeros. This mechanism allows to detect dead, hanging, or incompatible clients that generate unparseable packets. If zero, default value is used. If negative, the timeout is disabled.

long long choppy_playback_timeout

Timeout for choppy playback, in nanoseconds.

If there is constant stuttering during this period, the session is terminated (it can then automatically restart). Receiver itself is not terminated; if there are no sessions, it will produce zeros. This mechanism allows to detect situations when playback continues but there are frequent glitches, for example because there is a high ratio of late packets. If zero, default value is used. If negative, the timeout is disabled.

roc_metrics

#include <roc/metrics.h>
struct roc_sender_metrics

Sender slot metrics.

Represents metrics of single sender slot.

Public Members

int unused

Do not use.

struct roc_receiver_metrics

Receiver slot metrics.

Represents metrics of single receiver slot.

Public Members

unsigned int num_sessions

Number of sessions connected to receiver slot.

roc_session_metrics *sessions

Pointer to user-defined buffer for session metrics.

If user sets this pointer, it is used to write metrics for individual sessions.

size_t sessions_size

Number of structs in session metrics buffer.

If sessions pointer is set, sessions_size should define its size. If number of sessions is greater than provided size, only metrics for first sessions_size sessions will be written. Total number of sessions is always written to num_sessions.

struct roc_session_metrics

Receiver session metrics.

Represents metrics of single session connected to receiver.

Public Members

unsigned long long niq_latency

Estimated network-incoming-queue latency, in nanoseconds.

Defines how much media is buffered in receiver packet queue.

unsigned long long e2e_latency

Estimated end-to-end latency, in nanoseconds.

Defines how much time passes after frame is written to sender and before it is read from receiver.

Computations are based on RTCP and NTP. If ROC_PROTO_RTCP is not used, latency will be zero. If NTP clocks of sender and receiver are not synchronized, latency will be calculated incorrectly.

May be zero initially until enough data is transferred.

roc_log

#include <roc/log.h>
enum roc_log_level

Log level.

Values:

enumerator ROC_LOG_NONE

No messages.

Setting this level disables logging completely.

enumerator ROC_LOG_ERROR

Error messages.

Setting this level enables logging only when something goes wrong, e.g. a user operation can’t be completed, or there is not enough memory for a new session.

enumerator ROC_LOG_INFO

Informational messages.

Setting this level enables logging of important high-level events, like binding a new port or creating a new session.

enumerator ROC_LOG_DEBUG

Debug messages.

Setting this level enables logging of debug messages. Doesn’t affect performance.

enumerator ROC_LOG_TRACE

Debug messages (extra verbosity).

Setting this level enables verbose tracing. May cause significant slow down.

struct roc_log_message

Log message.

Public Members

roc_log_level level

Message log level.

const char *module

Name of the module that originated the message.

Pointer can be used only until roc_log_handler() returns.

const char *file

Name of the source code file.

May be NULL. Pointer can be used only until roc_log_handler() returns.

int line

Line number in the source code file.

unsigned long long time

Message timestamp, nanoseconds since Unix epoch.

unsigned long long pid

Platform-specific process ID.

unsigned long long tid

Platform-specific thread ID.

const char *text

Message text.

Pointer can be used only until roc_log_handler() returns.

typedef void (*roc_log_handler)(const roc_log_message *message, void *argument)

Log handler.

Parameters

  • message define message to be logged

  • argument is the argument passed to roc_log_set_handler

void roc_log_set_level(roc_log_level level)

Set maximum log level.

Messages with log levels higher than level will be dropped. By default the log level is set to ROC_LOG_ERROR.

Thread safety

Can be used concurrently.

void roc_log_set_handler(roc_log_handler handler, void *argument)

Set log handler.

If handler is not NULL, messages are passed to the handler. Otherwise, messages are printed to stderr. By default the log handler is set to NULL.

argument will be passed to the handler each time it is invoked.

It’s guaranteed that the previously set handler, if any, will not be used after this function returns.

Thread safety

Can be used concurrently. Handler calls are serialized, so the handler itself doesn’t need to be thread-safe.

roc_version

#include <roc/version.h>
ROC_VERSION_MAJOR

Major version component.

ROC_VERSION_MINOR

Minor version component.

ROC_VERSION_PATCH

Patch version component.

ROC_VERSION

Numeric version code.

See also

ROC_VERSION_CODE

ROC_VERSION_CODE(major, minor, patch)

Convert version triple to numeric version code.

Version codes can be compared direcrly, e.g.:

#if ROC_VERSION < ROC_VERSION_CODE(1, 2, 3)
...
#endif

struct roc_version

Version components.

Public Members

unsigned int major

Major version component.

unsigned int minor

Minor version component.

unsigned int patch

Patch version component.

unsigned int code

Numeric version code.

void roc_version_get(roc_version *version)

Retrieve version numbers.

This function can be used to retrieve actual run-time version of the library. It may be different from the compile-time version when using shared library.