From 8db419b1b9d5c1190409a835fc1a6f640764b94c Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sun, 8 Jun 2025 21:54:40 +0200 Subject: [PATCH] afh.h --- afh.h | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/afh.h b/afh.h index ba72d80e..1ce7fb21 100644 --- a/afh.h +++ b/afh.h @@ -1,12 +1,32 @@ /* Copyright (C) 2005 Andre Noll , see file COPYING. */ -/** \file afh.h Structures for audio format handling (para_server). */ +/** \file afh.h Audio format handlers + * + * The mission of an audio format handler is to tell whether a given file + * is an audio file of a certain type. The core of the API is the \ref + * audio_format_handler structure whose methods are called when an audio + * file is added to the database of para_server(1). Also the virtual + * streaming system calls the functions here to stream a file. + * + * More precisely, each time a file is added, the \ref + * audio_format_handler::get_file_info() method is called to initialize an \ref + * afh_info structure which contains all information needed for streaming, + * including the metadata tags. A serialized version of this structure is + * stored in the audio file table and referenced when the file is streamed. + * + * Each audio format handler is implemented in a dedicated .c file. For + * example, the audio format handler for the mp3 format is \ref mp3_afh.c. All + * helper functions decribed here are implemented in \ref afh_common.c, which + * also defines the array of audio format handlers known to para_server(1), + * para_afh(1) and para_recv(1). + */ /** * The tags used by all audio format handlers. * - * Paraslash only uses the more common tags. These are recognized - * for all supported audio formats. + * Paraslash only cares about the five metadata tags described in this + * structure. Each audio format handler is capable of reading and modifying + * these tags. */ struct taginfo { /** TPE1 (id3v2) / ARTIST (vorbis) / ART (aac)/ author(spx) */ @@ -29,7 +49,7 @@ struct afh_info { uint32_t seconds_total; /** Audio handler specific info about the file. */ char *techinfo; - /** Id3 tags, vorbis comments, aac tags. */ + /** Id3 tags, vorbis comments, aac tags, etc. */ struct taginfo tags; /** * The table that specifies the offset of the individual pieces in @@ -88,8 +108,6 @@ struct audio_format_handler { * this audio format handler is unable to decode the given file. On * success, the function must return a positive value and fill in the * given struct afh_info. - * - * \sa struct \ref afh_info. */ int (*get_file_info)(char *map, size_t numbytes, int fd, struct afh_info *afhi); -- 2.39.5