\section{fishsound.h File Reference}
\label{fishsound_8h}\index{fishsound.h@{fishsound.h}}
The libfishsound C API.  


{\tt \#include $<$fishsound/constants.h$>$}\par
{\tt \#include $<$fishsound/decode.h$>$}\par
{\tt \#include $<$fishsound/encode.h$>$}\par
{\tt \#include $<$fishsound/comments.h$>$}\par
{\tt \#include $<$fishsound/deprecated.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct {\bf FishSoundInfo}
\begin{CompactList}\small\item\em Info about a particular encoder/decoder instance. \item\end{CompactList}\item 
struct {\bf FishSoundFormat}
\begin{CompactList}\small\item\em Info about a particular sound format. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef void $\ast$ {\bf FishSound}
\begin{CompactList}\small\item\em An opaque handle to a FishSound. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int {\bf fish\_\-sound\_\-identify} (unsigned char $\ast$buf, long bytes)
\begin{CompactList}\small\item\em Identify a codec based on the first few bytes of data. \item\end{CompactList}\item 
{\bf FishSound} $\ast$ {\bf fish\_\-sound\_\-new} (int mode, {\bf FishSoundInfo} $\ast$fsinfo)
\begin{CompactList}\small\item\em Instantiate a new FishSound$\ast$ handle. \item\end{CompactList}\item 
long {\bf fish\_\-sound\_\-flush} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Flush any internally buffered data, forcing encode. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-reset} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Reset the codec state of a FishSound object. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-delete} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Delete a FishSound object. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-command} ({\bf FishSound} $\ast$fsound, int command, void $\ast$data, int datasize)
\begin{CompactList}\small\item\em Command interface. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-get\_\-interleave} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Query whether a FishSound object is using interleaved PCM. \item\end{CompactList}\item 
long {\bf fish\_\-sound\_\-get\_\-frameno} ({\bf FishSound} $\ast$fsound)
\begin{CompactList}\small\item\em Query the current frame number of a FishSound object. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-set\_\-frameno} ({\bf FishSound} $\ast$fsound, long frameno)
\begin{CompactList}\small\item\em Set the current frame number of a FishSound object. \item\end{CompactList}\item 
int {\bf fish\_\-sound\_\-prepare\_\-truncation} ({\bf FishSound} $\ast$fsound, long next\_\-granulepos, int next\_\-eos)
\begin{CompactList}\small\item\em Prepare truncation details for the next block of data. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
The libfishsound C API. 

\subsection{General usage}\label{fishsound_8h_general}
All 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}
libfishsound 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}
libfishsound 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. 

\subsection{Typedef Documentation}
\index{fishsound.h@{fishsound.h}!FishSound@{FishSound}}
\index{FishSound@{FishSound}!fishsound.h@{fishsound.h}}
\subsubsection[{FishSound}]{\setlength{\rightskip}{0pt plus 5cm}typedef void$\ast$ {\bf FishSound}}\label{fishsound_8h_8cfb7dfb102ad1af9ff35046aed3ccd9}


An opaque handle to a FishSound. 

This is returned by fishsound\_\-new() and is passed to all other fish\_\-sound\_\-$\ast$() functions. 

\subsection{Function Documentation}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-command@{fish\_\-sound\_\-command}}
\index{fish\_\-sound\_\-command@{fish\_\-sound\_\-command}!fishsound.h@{fishsound.h}}
\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}


Command interface. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\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}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -1 on failure \end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-delete@{fish\_\-sound\_\-delete}}
\index{fish\_\-sound\_\-delete@{fish\_\-sound\_\-delete}!fishsound.h@{fishsound.h}}
\subsubsection[{fish\_\-sound\_\-delete}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-delete ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_002e2dee1a7f736699dba5bec0a81426}


Delete a FishSound object. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -1 on failure \end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-flush@{fish\_\-sound\_\-flush}}
\index{fish\_\-sound\_\-flush@{fish\_\-sound\_\-flush}!fishsound.h@{fishsound.h}}
\subsubsection[{fish\_\-sound\_\-flush}]{\setlength{\rightskip}{0pt plus 5cm}long fish\_\-sound\_\-flush ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_b1672c542e09528b3dad3ee694b124d8}


Flush any internally buffered data, forcing encode. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -1 on failure \end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-get\_\-frameno@{fish\_\-sound\_\-get\_\-frameno}}
\index{fish\_\-sound\_\-get\_\-frameno@{fish\_\-sound\_\-get\_\-frameno}!fishsound.h@{fishsound.h}}
\subsubsection[{fish\_\-sound\_\-get\_\-frameno}]{\setlength{\rightskip}{0pt plus 5cm}long fish\_\-sound\_\-get\_\-frameno ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_d991f9f6887487f5d833de9480bcbe43}


Query the current frame number of a FishSound object. 

For 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.

For 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.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The current frame number \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]Invalid {\em fsound\/} \end{description}
\end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-get\_\-interleave@{fish\_\-sound\_\-get\_\-interleave}}
\index{fish\_\-sound\_\-get\_\-interleave@{fish\_\-sound\_\-get\_\-interleave}!fishsound.h@{fishsound.h}}
\subsubsection[{fish\_\-sound\_\-get\_\-interleave}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-get\_\-interleave ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_7bc2b75ad943e2da3147bf33882860c8}


Query whether a FishSound object is using interleaved PCM. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-identify@{fish\_\-sound\_\-identify}}
\index{fish\_\-sound\_\-identify@{fish\_\-sound\_\-identify}!fishsound.h@{fishsound.h}}
\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}


Identify a codec based on the first few bytes of data. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\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}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\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}
\end{Desc}
\begin{Desc}
\item[Note:]If {\em bytes\/} is exactly 8, then only a weak check is performed, which is fast but may return a false positive. 

If {\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}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-new@{fish\_\-sound\_\-new}}
\index{fish\_\-sound\_\-new@{fish\_\-sound\_\-new}!fishsound.h@{fishsound.h}}
\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}


Instantiate a new FishSound$\ast$ handle. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mode}]FISH\_\-SOUND\_\-DECODE or FISH\_\-SOUND\_\-ENCODE \item[{\em fsinfo}]Encoder configuration, may be NULL for FISH\_\-SOUND\_\-DECODE \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A new FishSound$\ast$ handle, or NULL on error \end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-prepare\_\-truncation@{fish\_\-sound\_\-prepare\_\-truncation}}
\index{fish\_\-sound\_\-prepare\_\-truncation@{fish\_\-sound\_\-prepare\_\-truncation}!fishsound.h@{fishsound.h}}
\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}


Prepare truncation details for the next block of data. 

The semantics of these parameters derives directly from Ogg encapsulation of Vorbis, described {\tt here}.

When 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.

When 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.

\begin{Desc}
\item[Parameters:]
\begin{description}
\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}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \item[{\em -1}]Invalid {\em fsound\/} \end{description}
\end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-reset@{fish\_\-sound\_\-reset}}
\index{fish\_\-sound\_\-reset@{fish\_\-sound\_\-reset}!fishsound.h@{fishsound.h}}
\subsubsection[{fish\_\-sound\_\-reset}]{\setlength{\rightskip}{0pt plus 5cm}int fish\_\-sound\_\-reset ({\bf FishSound} $\ast$ {\em fsound})}\label{fishsound_8h_546a521c2c3c3a2ee614ae3981fbc29f}


Reset the codec state of a FishSound object. 

When 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}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -1 on failure \end{Desc}
\index{fishsound.h@{fishsound.h}!fish\_\-sound\_\-set\_\-frameno@{fish\_\-sound\_\-set\_\-frameno}}
\index{fish\_\-sound\_\-set\_\-frameno@{fish\_\-sound\_\-set\_\-frameno}!fishsound.h@{fishsound.h}}
\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}


Set the current frame number of a FishSound object. 

When 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}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em fsound}]A FishSound$\ast$ handle \item[{\em frameno}]The current frame number. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \item[{\em -1}]Invalid {\em fsound\/} \end{description}
\end{Desc}
