ogg_afh_common.h File Reference

Structures and prototypes common to audio format handlers that use the ogg container format. More...

Data Structures
struct	oac_callback_info
	Callback structure provided by audio format handlers. More...

Functions
__malloc struct oac_custom_header *	oac_custom_header_new (void)
	Allocate and return a custom header structure. More...
void	oac_custom_header_init (int serial, struct oac_custom_header *h)
	Set the serial number of an allocated header structure. More...
int	oac_custom_header_append (ogg_packet *op, struct oac_custom_header *h)
	Submit an ogg packet to a custom header structure. More...
void	oac_custom_header_flush (struct oac_custom_header *h)
	Force remaining packets into an ogg page. More...
size_t	oac_custom_header_get (char **buf, struct oac_custom_header *h)
	Return the custom header buffer and deallocate resources. More...
int	oac_get_file_info (char *map, size_t numbytes, struct afh_info *afhi, struct oac_callback_info *ci)
	Pass first three ogg packets to callback and build the chunk table. More...
int	oac_rewrite_tags (const char *map, size_t mapsize, int fd, char *meta_packet, size_t meta_sz)
	Change meta tags of ogg files. More...

Detailed Description

Structures and prototypes common to audio format handlers that use the ogg container format.

Function Documentation

oac_custom_header_new()

__malloc struct oac_custom_header* oac_custom_header_new

(

void

)

Allocate and return a custom header structure.

For some audio codecs which employ the ogg container format, the server side wants to replace the meta tags at the beginning of the file because they are not needed for streaming and can be arbitrary large. The structure returned by this function is typically used as the ->private field of struct oac_callback_info for oac_get_file_info(). This allows the audio format handler to set up a custom header which is identical to the original header, but with the meta data part replaced by fixed length dummy contents.

Returns

The returned memory must be initialized with the serial number of the ogg stream before ogg packets can be submitted to it. This is not done here because the header structure is allocated before oac_get_file_info() is called, and the serial number is not known at this point.

See also

oac_custom_header_init().

References zalloc().

oac_custom_header_init()

void oac_custom_header_init	(	int	serial,
		struct oac_custom_header *	h
	)

Set the serial number of an allocated header structure.

Parameters

serial	Passed to the callback function.
h	As returned from oac_custom_header_new().

This function must be called before any packets are submitted.

oac_custom_header_append()

int oac_custom_header_append	(	ogg_packet *	op,
		struct oac_custom_header *	h
	)

Submit an ogg packet to a custom header structure.

Parameters

op	The packet to append.
h	Must be initialized.

The packet may be the one which was passed to the callback, or a completely different one, like a dummy metadata packet.

Returns

Standard.

oac_custom_header_flush()

void oac_custom_header_flush

(

struct oac_custom_header *

h

)

Force remaining packets into an ogg page.

Parameters

h	Should contain submitted but not yet flushed packets.

This is called after the first packet has been submitted with oac_custom_header_append() to make sure the first ogg page contains only this packet. Also when header processing is complete, the callbacks call this to force the previously submitted packets into a page.

References para_realloc().

oac_custom_header_get()

size_t oac_custom_header_get	(	char **	buf,
		struct oac_custom_header *	h
	)

Return the custom header buffer and deallocate resources.

This is called after the ogg packets which comprise the header have been submitted and flushed.

Parameters

buf	Result pointer.
h	Must not be used any more after the call.

Returns

The size of the header. This is the sum of the sizes of all ogg pages that have been flushed out.

oac_get_file_info()

int oac_get_file_info	(	char *	map,
		size_t	numbytes,
		struct afh_info *	afhi,
		struct oac_callback_info *	ci
	)

Pass first three ogg packets to callback and build the chunk table.

This function extracts the first three ogg packets of the audio data given by map and numbytes and passes each packet to the callback defined by ci.

If the packet callback indicates success and afhi is not NULL, the chunk table is built. Chunk zero contains the first three ogg packets while all other chunks consist of exactly one ogg page.

Parameters

map	Audio file data.
numbytes	The length of map.
afhi	Passed to the packet callback, contains chunk table.
ci	The callback structure.

Returns

Standard.

oac_rewrite_tags()

int oac_rewrite_tags	(	const char *	map,
		size_t	map_sz,
		int	fd,
		char *	meta_packet,
		size_t	meta_sz
	)

Change meta tags of ogg files.

Parameters

map	The (read-only) memory map of the input file.
map_sz	The size of the input file in bytes.
fd	The output file descriptor.
meta_packet	Codec-specific packet containing modified tags.
meta_sz	Size of the metadata packet.

This function writes a new ogg file content using file descriptor fd, which must correspond to a file which has been opened for writing. The second packet is supposed to contain the metadata, and is replaced by meta_packet. This output file has to be closed by the caller.

Returns

Standard.