paraslash Paraslash Audio Streaming
About   News   Download   Documentation   Development

Data Structures | Functions
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
serialPassed to the callback function.
hAs 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
opThe packet to append.
hMust 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
hShould 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
bufResult pointer.
hMust 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
mapAudio file data.
numbytesThe length of map.
afhiPassed to the packet callback, contains chunk table.
ciThe 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
mapThe (read-only) memory map of the input file.
map_szThe size of the input file in bytes.
fdThe output file descriptor.
meta_packetCodec-specific packet containing modified tags.
meta_szSize 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.