Encoding

Functions for encoding Ogg Opus files
These functions make it possible to encode Ogg Opus files.
OPE_EXPORT OggOpusEnc *	ope_encoder_create_file (const char *path, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
	Create a new OggOpus file.
OPE_EXPORT OggOpusEnc *	ope_encoder_create_callbacks (const OpusEncCallbacks *callbacks, void *user_data, OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
	Create a new OggOpus stream to be handled using callbacks.
OPE_EXPORT OggOpusEnc *	ope_encoder_create_pull (OggOpusComments *comments, opus_int32 rate, int channels, int family, int *error)
	Create a new OggOpus stream to be used along with.ope_encoder_get_page().
OPE_EXPORT int	ope_encoder_deferred_init_with_mapping (OggOpusEnc *enc, int family, int streams, int coupled_streams, const unsigned char *mapping)
	Deferred initialization of the encoder to force an explicit channel mapping.
OPE_EXPORT int	ope_encoder_write_float (OggOpusEnc *enc, const float *pcm, int samples_per_channel)
	Add/encode any number of float samples to the stream.
OPE_EXPORT int	ope_encoder_write (OggOpusEnc *enc, const opus_int16 *pcm, int samples_per_channel)
	Add/encode any number of 16-bit linear samples to the stream.
OPE_EXPORT int	ope_encoder_get_page (OggOpusEnc *enc, unsigned char **page, opus_int32 *len, int flush)
	Get the next page from the stream (only if using ope_encoder_create_pull()).
OPE_EXPORT int	ope_encoder_drain (OggOpusEnc *enc)
	Finalizes the stream, but does not deallocate the object.
OPE_EXPORT void	ope_encoder_destroy (OggOpusEnc *enc)
	Deallocates the obect.
OPE_EXPORT int	ope_encoder_chain_current (OggOpusEnc *enc, OggOpusComments *comments)
	Ends the stream and create a new stream within the same file.
OPE_EXPORT int	ope_encoder_continue_new_file (OggOpusEnc *enc, const char *path, OggOpusComments *comments)
	Ends the stream and create a new file.
OPE_EXPORT int	ope_encoder_continue_new_callbacks (OggOpusEnc *enc, void *user_data, OggOpusComments *comments)
	Ends the stream and create a new file (callback-based).
OPE_EXPORT int	ope_encoder_flush_header (OggOpusEnc *enc)
	Write out the header now rather than wait for audio to begin.
OPE_EXPORT int	ope_encoder_ctl (OggOpusEnc *enc, int request,...)
	Sets encoder options.
OPE_EXPORT const char *	ope_strerror (int error)
	Converts a libopusenc error code into a human readable string.
OPE_EXPORT const char *	ope_get_version_string (void)
	Returns a string representing the version of libopusenc being used at run time.
OPE_EXPORT int	ope_get_abi_version (void)
	ABI version for this header.

---

Function Documentation

OPE_EXPORT OggOpusEnc* ope_encoder_create_file	(	const char *	path,
		OggOpusComments *	comments,
		opus_int32	rate,
		int	channels,
		int	family,
		int *	error
	)

Create a new OggOpus file.

Parameters:

	path	Path where to create the file
	comments	Comments associated with the stream
	rate	Input sampling rate (48 kHz is faster)
	channels	Number of channels
	family	Mapping family (0 for mono/stereo, 1 for surround)
[out]	error	Error code (NULL if no error is to be returned)

Returns:

Newly-created encoder.

OPE_EXPORT OggOpusEnc* ope_encoder_create_callbacks	(	const OpusEncCallbacks *	callbacks,
		void *	user_data,
		OggOpusComments *	comments,
		opus_int32	rate,
		int	channels,
		int	family,
		int *	error
	)

Create a new OggOpus stream to be handled using callbacks.

Parameters:

	callbacks	Callback functions
	user_data	Pointer to be associated with the stream and passed to the callbacks
	comments	Comments associated with the stream
	rate	Input sampling rate (48 kHz is faster)
	channels	Number of channels
	family	Mapping family (0 for mono/stereo, 1 for surround)
[out]	error	Error code (NULL if no error is to be returned)

Returns:

Newly-created encoder.

OPE_EXPORT OggOpusEnc* ope_encoder_create_pull	(	OggOpusComments *	comments,
		opus_int32	rate,
		int	channels,
		int	family,
		int *	error
	)

Create a new OggOpus stream to be used along with.ope_encoder_get_page().

This is mostly useful for muxing with other streams.

Parameters:

	comments	Comments associated with the stream
	rate	Input sampling rate (48 kHz is faster)
	channels	Number of channels
	family	Mapping family (0 for mono/stereo, 1 for surround)
[out]	error	Error code (NULL if no error is to be returned)

Returns:

Newly-created encoder.

OPE_EXPORT int ope_encoder_deferred_init_with_mapping	(	OggOpusEnc *	enc,
		int	family,
		int	streams,
		int	coupled_streams,
		const unsigned char *	mapping
	)

Deferred initialization of the encoder to force an explicit channel mapping.

This can be used to override the default channel coupling, but using it for regular surround will almost certainly lead to worse quality.

Parameters:

[in,out]	enc	Encoder
	family	Mapping family (0 for mono/stereo, 1 for surround)
	streams	Total number of streams
	coupled_streams	Number of coupled streams
	mapping	Channel mapping

Returns:

Error code

OPE_EXPORT int ope_encoder_write_float	(	OggOpusEnc *	enc,
		const float *	pcm,
		int	samples_per_channel
	)

Add/encode any number of float samples to the stream.

Parameters:

[in,out]	enc	Encoder
	pcm	Floating-point PCM values in the +/-1 range (interleaved if multiple channels)
	samples_per_channel	Number of samples for each channel

Returns:

Error code

OPE_EXPORT int ope_encoder_write	(	OggOpusEnc *	enc,
		const opus_int16 *	pcm,
		int	samples_per_channel
	)

Add/encode any number of 16-bit linear samples to the stream.

Parameters:

[in,out]	enc	Encoder
	pcm	Linear 16-bit PCM values in the [-32768,32767] range (interleaved if multiple channels)
	samples_per_channel	Number of samples for each channel

Returns:

Error code

OPE_EXPORT int ope_encoder_get_page	(	OggOpusEnc *	enc,
		unsigned char **	page,
		opus_int32 *	len,
		int	flush
	)

Get the next page from the stream (only if using ope_encoder_create_pull()).

Parameters:

[in,out]	enc	Encoder
[out]	page	Next available encoded page
[out]	len	Size (in bytes) of the page returned
	flush	If non-zero, forces a flush of the page (if any data avaiable)

Returns:

1 if there is a page available, 0 if not.

OPE_EXPORT int ope_encoder_drain

(

OggOpusEnc *

enc

)

Finalizes the stream, but does not deallocate the object.

Parameters:

[in,out]

enc

Encoder

Returns:

Error code

OPE_EXPORT void ope_encoder_destroy

(

OggOpusEnc *

enc

)

Deallocates the obect.

Make sure to ope_drain() first.

Parameters:

[in,out]

enc

Encoder

OPE_EXPORT int ope_encoder_chain_current	(	OggOpusEnc *	enc,
		OggOpusComments *	comments
	)

Ends the stream and create a new stream within the same file.

Parameters:

[in,out]	enc	Encoder
	comments	Comments associated with the stream

Returns:

Error code

OPE_EXPORT int ope_encoder_continue_new_file	(	OggOpusEnc *	enc,
		const char *	path,
		OggOpusComments *	comments
	)

Ends the stream and create a new file.

Parameters:

[in,out]	enc	Encoder
	path	Path where to write the new file
	comments	Comments associated with the stream

Returns:

Error code

OPE_EXPORT int ope_encoder_continue_new_callbacks	(	OggOpusEnc *	enc,
		void *	user_data,
		OggOpusComments *	comments
	)

Ends the stream and create a new file (callback-based).

Parameters:

[in,out]	enc	Encoder
	user_data	Pointer to be associated with the new stream and passed to the callbacks
	comments	Comments associated with the stream

Returns:

Error code

OPE_EXPORT int ope_encoder_flush_header

(

OggOpusEnc *

enc

)

Write out the header now rather than wait for audio to begin.

Parameters:

[in,out]

enc

Encoder

Returns:

Error code

OPE_EXPORT int ope_encoder_ctl	(	OggOpusEnc *	enc,
		int	request,
			...
	)

Sets encoder options.

Parameters:

[in,out]	enc	Encoder
	request	Use a request macro

Returns:

Error code

OPE_EXPORT const char* ope_strerror

(

int

error

)

Converts a libopusenc error code into a human readable string.

Parameters:

error

Error number

Returns:

Error string

OPE_EXPORT const char* ope_get_version_string

(

void

)

Returns a string representing the version of libopusenc being used at run time.

Returns:

A string describing the version of this library

OPE_EXPORT int ope_get_abi_version

(

void

)

ABI version for this header.

Can be used to check for features at run time.

Returns:

An integer representing the ABI version