1\section{fishsound.h File Reference} 2\label{fishsound_8h}\index{fishsound.h@{fishsound.h}} 3The libfishsound C API. 4 5 6{\tt \#include $<$fishsound/constants.h$>$}\par 7{\tt \#include $<$fishsound/decode.h$>$}\par 8{\tt \#include $<$fishsound/encode.h$>$}\par 9{\tt \#include $<$fishsound/comments.h$>$}\par 10{\tt \#include $<$fishsound/deprecated.h$>$}\par 11\subsection*{Data Structures} 12\begin{CompactItemize} 13\item 14struct {\bf FishSoundInfo} 15\begin{CompactList}\small\item\em Info about a particular encoder/decoder instance. \item\end{CompactList}\item 16struct {\bf FishSoundFormat} 17\begin{CompactList}\small\item\em Info about a particular sound format. \item\end{CompactList}\end{CompactItemize} 18\subsection*{Typedefs} 19\begin{CompactItemize} 20\item 21typedef void $\ast$ {\bf FishSound} 22\begin{CompactList}\small\item\em An opaque handle to a FishSound. \item\end{CompactList}\end{CompactItemize} 23\subsection*{Functions} 24\begin{CompactItemize} 25\item 26int {\bf fish\_\-sound\_\-identify} (unsigned char $\ast$buf, long bytes) 27\begin{CompactList}\small\item\em Identify a codec based on the first few bytes of data. \item\end{CompactList}\item 28{\bf FishSound} $\ast$ {\bf fish\_\-sound\_\-new} (int mode, {\bf FishSoundInfo} $\ast$fsinfo) 29\begin{CompactList}\small\item\em Instantiate a new FishSound$\ast$ handle. \item\end{CompactList}\item 30long {\bf fish\_\-sound\_\-flush} ({\bf FishSound} $\ast$fsound) 31\begin{CompactList}\small\item\em Flush any internally buffered data, forcing encode. \item\end{CompactList}\item 32int {\bf fish\_\-sound\_\-reset} ({\bf FishSound} $\ast$fsound) 33\begin{CompactList}\small\item\em Reset the codec state of a FishSound object. \item\end{CompactList}\item 34int {\bf fish\_\-sound\_\-delete} ({\bf FishSound} $\ast$fsound) 35\begin{CompactList}\small\item\em Delete a FishSound object. \item\end{CompactList}\item 36int {\bf fish\_\-sound\_\-command} ({\bf FishSound} $\ast$fsound, int command, void $\ast$data, int datasize) 37\begin{CompactList}\small\item\em Command interface. \item\end{CompactList}\item 38int {\bf fish\_\-sound\_\-get\_\-interleave} ({\bf FishSound} $\ast$fsound) 39\begin{CompactList}\small\item\em Query whether a FishSound object is using interleaved PCM. \item\end{CompactList}\item 40long {\bf fish\_\-sound\_\-get\_\-frameno} ({\bf FishSound} $\ast$fsound) 41\begin{CompactList}\small\item\em Query the current frame number of a FishSound object. \item\end{CompactList}\item 42int {\bf fish\_\-sound\_\-set\_\-frameno} ({\bf FishSound} $\ast$fsound, long frameno) 43\begin{CompactList}\small\item\em Set the current frame number of a FishSound object. \item\end{CompactList}\item 44int {\bf fish\_\-sound\_\-prepare\_\-truncation} ({\bf FishSound} $\ast$fsound, long next\_\-granulepos, int next\_\-eos) 45\begin{CompactList}\small\item\em Prepare truncation details for the next block of data. \item\end{CompactList}\end{CompactItemize} 46 47 48\subsection{Detailed Description} 49The libfishsound C API. 50 51\subsection{General usage}\label{fishsound_8h_general} 52All access is managed via a FishSound$\ast$ handle. This is instantiated using \doxyref{fish\_\-sound\_\-new()}{p.}{fishsound_8h_decddfef35cbbddcc8a76b28c365c527} and should be deleted with \doxyref{fish\_\-sound\_\-delete()}{p.}{fishsound_8h_002e2dee1a7f736699dba5bec0a81426} when no longer required. If there is a discontinuity in the input data (eg. after seeking in an input file), call \doxyref{fish\_\-sound\_\-reset()}{p.}{fishsound_8h_546a521c2c3c3a2ee614ae3981fbc29f} to reset the internal codec state.\subsection{Decoding}\label{fishsound_8h_decoding} 53libfishsound provides callback based decoding: you feed it encoded audio data, and it will call your callback with decoded PCM. A more detailed explanation and a full example of decoding Ogg FLAC, Speex and Ogg Vorbis files is provided in the \doxyref{Decoding audio data }{p.}{group__decode} section.\subsection{Encoding}\label{fishsound_8h_encoding} 54libfishsound provides callback based encoding: you feed it PCM audio, and it will call your callback with encoded audio data. A more detailed explanation and a full example of encoding Ogg FLAC, Speex and Ogg Vorbis files is provided in the \doxyref{Encoding audio data }{p.}{group__encode} section. 55 56\subsection{Typedef Documentation} 57\index{fishsound.h@{fishsound.h}!FishSound@{FishSound}} 58\index{FishSound@{FishSound}!fishsound.h@{fishsound.h}} 59\subsubsection[{FishSound}]{\setlength{\rightskip}{0pt plus 5cm}typedef void$\ast$ {\bf FishSound}}\label{fishsound_8h_8cfb7dfb102ad1af9ff35046aed3ccd9} 60 61 62An opaque handle to a FishSound. 63 64This is returned by fishsound\_\-new() and is passed to all other fish\_\-sound\_\-$\ast$() functions. 65 66\subsection{Function Documentation} 67\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-command@{fish\_\-sound\_\-command}} 68\index{fish\_\-sound\_\-command@{fish\_\-sound\_\-command}!fishsound.h@{fishsound.h}} 69\subsubsection[{fish\_\-sound\_\-command}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-command ({\bf FishSound} $\ast$ {\em fsound}, \/ int {\em command}, \/ void $\ast$ {\em data}, \/ int {\em datasize})}\label{fishsound_8h_35c5182901b71a2514bc9a8f2ec839c7} 70 71 72Command interface. 73 74\begin{Desc} 75\item[Parameters:] 76\begin{description} 77\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em command}]The command action \item[{\em data}]Command data \item[{\em datasize}]Size of the data in bytes \end{description} 78\end{Desc} 79\begin{Desc} 80\item[Returns:]0 on success, -1 on failure \end{Desc} 81\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-delete@{fish\_\-sound\_\-delete}} 82\index{fish\_\-sound\_\-delete@{fish\_\-sound\_\-delete}!fishsound.h@{fishsound.h}} 83\subsubsection[{fish\_\-sound\_\-delete}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-delete ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_002e2dee1a7f736699dba5bec0a81426} 84 85 86Delete a FishSound object. 87 88\begin{Desc} 89\item[Parameters:] 90\begin{description} 91\item[{\em fsound}]A FishSound$\ast$ handle \end{description} 92\end{Desc} 93\begin{Desc} 94\item[Returns:]0 on success, -1 on failure \end{Desc} 95\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-flush@{fish\_\-sound\_\-flush}} 96\index{fish\_\-sound\_\-flush@{fish\_\-sound\_\-flush}!fishsound.h@{fishsound.h}} 97\subsubsection[{fish\_\-sound\_\-flush}]{\setlength{\rightskip}{0pt plus 5cm}long fish\_\-sound\_\-flush ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_b1672c542e09528b3dad3ee694b124d8} 98 99 100Flush any internally buffered data, forcing encode. 101 102\begin{Desc} 103\item[Parameters:] 104\begin{description} 105\item[{\em fsound}]A FishSound$\ast$ handle \end{description} 106\end{Desc} 107\begin{Desc} 108\item[Returns:]0 on success, -1 on failure \end{Desc} 109\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-get\_\-frameno@{fish\_\-sound\_\-get\_\-frameno}} 110\index{fish\_\-sound\_\-get\_\-frameno@{fish\_\-sound\_\-get\_\-frameno}!fishsound.h@{fishsound.h}} 111\subsubsection[{fish\_\-sound\_\-get\_\-frameno}]{\setlength{\rightskip}{0pt plus 5cm}long fish\_\-sound\_\-get\_\-frameno ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_d991f9f6887487f5d833de9480bcbe43} 112 113 114Query the current frame number of a FishSound object. 115 116For decoding, this is the greatest frame index that has been decoded and made available to a FishSoundDecoded callback. This function is safe to call from within a FishSoundDecoded callback, and corresponds to the frame number of the last frame in the current decoded block. 117 118For encoding, this is the greatest frame index that has been encoded. This function is safe to call from within a FishSoundEncoded callback, and corresponds to the frame number of the last frame encoded in the current block. 119 120\begin{Desc} 121\item[Parameters:] 122\begin{description} 123\item[{\em fsound}]A FishSound$\ast$ handle \end{description} 124\end{Desc} 125\begin{Desc} 126\item[Returns:]The current frame number \end{Desc} 127\begin{Desc} 128\item[Return values:] 129\begin{description} 130\item[{\em -1}]Invalid {\em fsound\/} \end{description} 131\end{Desc} 132\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-get\_\-interleave@{fish\_\-sound\_\-get\_\-interleave}} 133\index{fish\_\-sound\_\-get\_\-interleave@{fish\_\-sound\_\-get\_\-interleave}!fishsound.h@{fishsound.h}} 134\subsubsection[{fish\_\-sound\_\-get\_\-interleave}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-get\_\-interleave ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_7bc2b75ad943e2da3147bf33882860c8} 135 136 137Query whether a FishSound object is using interleaved PCM. 138 139\begin{Desc} 140\item[Parameters:] 141\begin{description} 142\item[{\em fsound}]A FishSound$\ast$ handle \end{description} 143\end{Desc} 144\begin{Desc} 145\item[Return values:] 146\begin{description} 147\item[{\em 0}]{\em fsound\/} uses non-interleaved PCM \item[{\em 1}]{\em fsound\/} uses interleaved PCM \item[{\em -1}]Invalid {\em fsound\/}, or out of memory. \end{description} 148\end{Desc} 149\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-identify@{fish\_\-sound\_\-identify}} 150\index{fish\_\-sound\_\-identify@{fish\_\-sound\_\-identify}!fishsound.h@{fishsound.h}} 151\subsubsection[{fish\_\-sound\_\-identify}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-identify (unsigned char $\ast$ {\em buf}, \/ long {\em bytes})}\label{fishsound_8h_2776f39cfa1540b1da3c9d423de15ae9} 152 153 154Identify a codec based on the first few bytes of data. 155 156\begin{Desc} 157\item[Parameters:] 158\begin{description} 159\item[{\em buf}]A pointer to the first few bytes of the data \item[{\em bytes}]The count of bytes available at buf \end{description} 160\end{Desc} 161\begin{Desc} 162\item[Return values:] 163\begin{description} 164\item[{\em FISH\_\-SOUND\_\-xxxxxx}]FISH\_\-SOUND\_\-VORBIS, FISH\_\-SOUND\_\-SPEEX or FISH\_\-SOUND\_\-FLAC if {\em buf\/} was identified as the initial bytes of a supported codec \item[{\em FISH\_\-SOUND\_\-UNKNOWN}]if the codec could not be identified \item[{\em FISH\_\-SOUND\_\-ERR\_\-SHORT\_\-IDENTIFY}]if {\em bytes\/} is less than 8 \end{description} 165\end{Desc} 166\begin{Desc} 167\item[Note:]If {\em bytes\/} is exactly 8, then only a weak check is performed, which is fast but may return a false positive. 168 169If {\em bytes\/} is greater than 8, then a stronger check is performed in which an attempt is made to decode {\em buf\/} as the initial header of each supported codec. This is unlikely to return a false positive but is only useful if {\em buf\/} is the entire payload of a packet derived from a lower layer such as Ogg framing or UDP datagrams. \end{Desc} 170\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-new@{fish\_\-sound\_\-new}} 171\index{fish\_\-sound\_\-new@{fish\_\-sound\_\-new}!fishsound.h@{fishsound.h}} 172\subsubsection[{fish\_\-sound\_\-new}]{\setlength{\rightskip}{0pt plus 5cm}{\bf FishSound}$\ast$ fish\_\-sound\_\-new (int {\em mode}, \/ {\bf FishSoundInfo} $\ast$ {\em fsinfo})}\label{fishsound_8h_decddfef35cbbddcc8a76b28c365c527} 173 174 175Instantiate a new FishSound$\ast$ handle. 176 177\begin{Desc} 178\item[Parameters:] 179\begin{description} 180\item[{\em mode}]FISH\_\-SOUND\_\-DECODE or FISH\_\-SOUND\_\-ENCODE \item[{\em fsinfo}]Encoder configuration, may be NULL for FISH\_\-SOUND\_\-DECODE \end{description} 181\end{Desc} 182\begin{Desc} 183\item[Returns:]A new FishSound$\ast$ handle, or NULL on error \end{Desc} 184\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-prepare\_\-truncation@{fish\_\-sound\_\-prepare\_\-truncation}} 185\index{fish\_\-sound\_\-prepare\_\-truncation@{fish\_\-sound\_\-prepare\_\-truncation}!fishsound.h@{fishsound.h}} 186\subsubsection[{fish\_\-sound\_\-prepare\_\-truncation}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-prepare\_\-truncation ({\bf FishSound} $\ast$ {\em fsound}, \/ long {\em next\_\-granulepos}, \/ int {\em next\_\-eos})}\label{fishsound_8h_6f4818e09b8323d8461331f46f13ab6a} 187 188 189Prepare truncation details for the next block of data. 190 191The semantics of these parameters derives directly from Ogg encapsulation of Vorbis, described {\tt here}. 192 193When decoding from Ogg, you should call this function with the {\em granulepos\/} and {\em eos\/} of the {\em ogg\_\-packet\/} structure. This call should be made before passing the packet's data to \doxyref{fish\_\-sound\_\-decode()}{p.}{decode_8h_070a1843d6990a00e2471945d40645c7}. Failure to do so may result in minor decode errors on the first and/or last packet of the stream. 194 195When encoding into Ogg, you should call this function with the {\em granulepos\/} and {\em eos\/} that will be used for the {\em ogg\_\-packet\/} structure. This call should be made before passing the block of audio data to fish\_\-sound\_\-encode\_\-$\ast$(). Failure to do so may result in minor encoding errors on the first and/or last packet of the stream. 196 197\begin{Desc} 198\item[Parameters:] 199\begin{description} 200\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em next\_\-granulepos}]The \char`\"{}granulepos\char`\"{} for the next block to decode. If unknown, set {\em next\_\-granulepos\/} to -1. Otherwise, {\em next\_\-granulepos\/} specifies the frameno of the final frame in the block. This is authoritative, hence can be used to indicate various forms of truncation at the beginning or end of a stream. Mid-stream, a later-than-expected \char`\"{}granulepos\char`\"{} indicates that some data was missing. \item[{\em next\_\-eos}]A boolean indicating whether the next data block will be the last in the stream. \end{description} 201\end{Desc} 202\begin{Desc} 203\item[Return values:] 204\begin{description} 205\item[{\em 0}]Success \item[{\em -1}]Invalid {\em fsound\/} \end{description} 206\end{Desc} 207\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-reset@{fish\_\-sound\_\-reset}} 208\index{fish\_\-sound\_\-reset@{fish\_\-sound\_\-reset}!fishsound.h@{fishsound.h}} 209\subsubsection[{fish\_\-sound\_\-reset}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-reset ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_546a521c2c3c3a2ee614ae3981fbc29f} 210 211 212Reset the codec state of a FishSound object. 213 214When decoding from a seekable file, \doxyref{fish\_\-sound\_\-reset()}{p.}{fishsound_8h_546a521c2c3c3a2ee614ae3981fbc29f} should be called after any seek operations. See also \doxyref{fish\_\-sound\_\-set\_\-frameno()}{p.}{fishsound_8h_0d508075ecdd834ab5a4504f5e85f66b}. 215 216\begin{Desc} 217\item[Parameters:] 218\begin{description} 219\item[{\em fsound}]A FishSound$\ast$ handle \end{description} 220\end{Desc} 221\begin{Desc} 222\item[Returns:]0 on success, -1 on failure \end{Desc} 223\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-set\_\-frameno@{fish\_\-sound\_\-set\_\-frameno}} 224\index{fish\_\-sound\_\-set\_\-frameno@{fish\_\-sound\_\-set\_\-frameno}!fishsound.h@{fishsound.h}} 225\subsubsection[{fish\_\-sound\_\-set\_\-frameno}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-set\_\-frameno ({\bf FishSound} $\ast$ {\em fsound}, \/ long {\em frameno})}\label{fishsound_8h_0d508075ecdd834ab5a4504f5e85f66b} 226 227 228Set the current frame number of a FishSound object. 229 230When decoding from a seekable file, \doxyref{fish\_\-sound\_\-set\_\-frameno()}{p.}{fishsound_8h_0d508075ecdd834ab5a4504f5e85f66b} should be called after any seek operations, otherwise the value returned by \doxyref{fish\_\-sound\_\-get\_\-frameno()}{p.}{fishsound_8h_d991f9f6887487f5d833de9480bcbe43} will simply continue to increment. See also \doxyref{fish\_\-sound\_\-reset()}{p.}{fishsound_8h_546a521c2c3c3a2ee614ae3981fbc29f}. 231 232\begin{Desc} 233\item[Parameters:] 234\begin{description} 235\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em frameno}]The current frame number. \end{description} 236\end{Desc} 237\begin{Desc} 238\item[Return values:] 239\begin{description} 240\item[{\em 0}]Success \item[{\em -1}]Invalid {\em fsound\/} \end{description} 241\end{Desc} 242