Decoding Raw Samples

quiet_decoder

struct quiet_decoder;

typedef struct quiet_decoder quiet_decoder;

quiet_decoder_create

quiet_decoder *

quiet_decoder_create(const quiet_decoder_options *opt,

                     float sample_rate);

quiet_decoder_create creates and initializes a new libquiet decoder for a given set of options and sample rate.

It is recommended to use the default sample rate of your device in order to avoid any possible implicit resampling, which can distort samples.

Parameters

opt - quiet_decoder_options containing decoder configuration

sample_rate - Sample rate that decoder will consume at

Returns

pointer to new decoder object, or NULL if creation failed.

quiet_decoder_recv

ssize_t

quiet_decoder_recv(quiet_decoder *d,

                   uint8_t *data,

                   size_t len);

quiet_decoder_recv reads one frame from the decoder's receive buffer. By default, this is a nonblocking call and will fail quickly if no frames are ready to be received. However, if quiet_decoder_set_blocking is called prior to this call, then it will wait for as much as the timeout specified there until it can read a frame.

If the user's supplied buffer is smaller than the length of the received frame, then only len bytes will be copied to data. The remaining bytes will be discarded.

This function will never return frames for which the checksum has failed.

If libquiet was built and linked with pthread, then this function may be called from any thread, and by multiple threads concurrently.

quiet_decoder_recv will return 0 if the decoder has been closed and the receive queue is empty.

quiet_decoder_recv will return a negative value and set the last error to quiet_timedout if blocking mode is enabled and no frame could be read before the timeout.

quiet_decoder_recv will return a negative value and set the last error to quiet_would_block if nonblocking mode is enabled and no frame was available.

Parameters

d - decoder object

data - user buffer which quiet will write received frame into

len - length of user-supplied buffer

Returns

number of bytes written to buffer, 0 at EOF, or -1 if no frames available

quiet_decoder_set_blocking

void

quiet_decoder_set_blocking(quiet_decoder *d,

                           time_t sec,

                           long nano);

quiet_decoder_set_blocking changes the behavior of quiet_decoder_recv so that it will block until a frame can be read. It will block for approximately (nano + 1000000000*sec) nanoseconds.

If sec and nano are both 0, then quiet_decoder_recv will block indefinitely until a frame is received.

This function is only supported on systems with pthread. Calling quiet_decoder_set_blocking on a host without pthread will assert false.

Parameters

d - decoder object

sec - time_t number of seconds to block for

nano - long number of nanoseconds to block for

quiet_decoder_set_nonblocking

void

quiet_decoder_set_nonblocking(quiet_decoder *d);

quiet_decoder_set_nonblocking changes the behavior of quiet_decoder_recv so that it will not block if it cannot read a frame. This function restores the default behavior after quiet_decoder_set_blocking has been called.

Parameters

d - decoder object

quiet_decoder_consume

void

quiet_decoder_consume(quiet_decoder *d,

                      const quiet_sample_t *samplebuf,

                      size_t sample_len);

quiet_decoder_consume consumes sound samples and decodes them to frames. These can be samples obtained directly from a sound file, a soundcard's microphone, or any other source which can receive quiet_sample_t (float).

If you are using a soundcard, it is recommended to use the largest block size offered. Typically, this is 16384 samples. Larger block sizes will help hide uneven latencies in the decoding process and ensure smoother reception at the cost of longer latencies.

Parameters

d - decoder object

samplebuf - array of samples received from sound card

sample_len - number of samples in samplebuf

quiet_decoder_frame_in_progress

bool

quiet_decoder_frame_in_progress(quiet_decoder *d);

quiet_decoder_frame_in_progress determines if a frame is likely in the process of being received. It inspects information in the decoding process and will be relevant to the last call to quiet_decoder_consume. There is no guarantee of accuracy from this function, and both false-negatives and false-positives can occur.

The output of this function can be useful to avoid collisions when two pairs of encoders/decoders share the same channel, e.g. in half-duplex.

This function must be called from the same thread which calls quiet_decoder_consume.

Parameters

d - decoder object

Returns

true if a frame is likely being received

quiet_decoder_flush

void

quiet_decoder_flush(quiet_decoder *d);

quiet_decoder_flush empties out all internal buffers and attempts to decode them

This function need only be called after the sound stream has stopped. It is especially useful for reading from sound files where there are no trailing samples to "push" the decoded data through the decoder's filters

Parameters

d - decoder object

quiet_decoder_close

void

quiet_decoder_close(quiet_decoder *d);

quiet_decoder_close closes the decoder object. Future calls to quiet_decoder_consume will still attempt the decoding process but will not enqueue any decoded frames into the receive queue, e.g. they become cpu-expensive no-ops. Any previously enqueued frames can still be read out by quiet_decoder_recv, and once the receive queue is empty, quiet_decoder_recv will set the last error to quiet_closed.

Parameters

d - decoder object

quiet_decoder_checksum_fails

unsigned int

quiet_decoder_checksum_fails(const quiet_decoder *d);

quiet_decoder_checksum_fails returns the total number of frames decoded but which failed checksum across the lifetime of the decoder.

Parameters

d - decoder object

Returns

Total number of frames received with failed checksums

quiet_decoder_consume_stats

const quiet_decoder_frame_stats *

quiet_decoder_consume_stats(quiet_decoder *d,

                            size_t *num_frames);

quiet_decoder_consume_stats returns detailed info about the decoding process from the last call to quiet_decoder_consume_stats. It will save information on up to 8 frames. This includes frames which failed checksum. If quiet_decoder_consume found more than 8 frames, then information on only the first 8 frames will be saved.

In order to use this functionality, quiet_decoder_enable_stats must be called on the decoder object before calling quiet_decoder_consume.

This function must be called from the same thread that calls quiet_decoder_consume.

Parameters

d - decoder object

num_frames - number of frames at returned pointer

Returns

quiet_decoder_frame_stats which is an array of structs containing stats info, num_frames long

quiet_decoder_recv_stats

const quiet_decoder_frame_stats *

quiet_decoder_recv_stats(quiet_decoder *d);

quiet_decoder_enable_stats

void

quiet_decoder_enable_stats(quiet_decoder *d);

quiet_decoder_enable_stats allocates the required memory needed to save symbol and other information on each frame decode. Italso adds a small overhead needed to copy this information into an internal buffer.

By default, stats collection is disabled. Therefore, if the user would like to use quiet_decoder_consume_stats, then they must first call quiet_decoder_enable_stats.

Parameters

d - decoder object

quiet_decoder_disable_stats

void

quiet_decoder_disable_stats(quiet_decoder *d);

quiet_decoder_disable_stats frees all memory associated with stats collection.

Parameters

d - decoder object

quiet_decoder_set_stats_blocking

void

quiet_decoder_set_stats_blocking(quiet_decoder *d,

                                 time_t sec,

                                 long nano);

quiet_decoder_set_stats_nonblocking

void

quiet_decoder_set_stats_nonblocking(quiet_decoder *d);

quiet_decoder_destroy

void

quiet_decoder_destroy(quiet_decoder *d);

quiet_decoder_destroy releases all resources allocated by the quiet_decoder. After calling this function, the user should not call any other decoder functions on the decoder.

Parameters

d - decoder object