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