1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: sndfile.tex 3%% Purpose: wxMMedia docs 4%% Author: Guilhem Lavaux <lavaux@easynet.fr> 5%% Modified by: 6%% Created: 2000 7%% RCS-ID: $Id: sndfile.tex 7528 2000-06-04 08:38:36Z GL $ 8%% Copyright: (c) wxWindows team 9%% Licence: wxWindows licence 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11\section{\class{wxSoundFileStream}}\label{wxsoundfilestream} 12 13Base class for file coders/decoders. This class is not constructor (it is an abstract 14class). 15 16\wxheading{Derived from} 17 18\helpref{wxSoundStream}{wxsoundstream} 19 20\wxheading{Include file} 21 22wx/sndfile.h 23 24\wxheading{Data structures} 25 26\latexignore{\rtfignore{\wxheading{Members}}} 27 28\membersection{wxSoundFileStream::wxSoundFileStream}\label{wxsoundfilestreamwxsoundfilestream} 29 30\func{}{wxSoundFileStream}{\param{wxInputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}} 31 32It constructs a new file decoder object which will send 33audio data to the specified sound stream. 34The {\it stream} is the input stream to be decoded. The 35{\it io\_sound} is the destination sound stream. 36Once it has been constructed, you cannot change any of 37the specified streams nor the direction of the stream. 38 39You will have access to the playback functions. 40 41\func{}{wxSoundFileStream}{\param{wxOutputStream\& }{stream}, \param{wxSoundStream\& }{io\_sound}} 42 43It constructs a new file coder object which will get 44data to be recorded from the specified sound stream. 45The {\it stream} is the output wxStream. The {\it io\_sound} 46is the source sound stream of the audio data. Once 47it has been constructed, you cannot change any of 48the specified streams nor the direction of the stream. 49 50\membersection{wxSoundFileStream::\destruct{wxSoundFileStream}}\label{wxsoundfilestreamdtor} 51\func{}{\destruct{wxSoundFileStream}}{\void} 52 53It destroys the current sound file codec. 54 55\membersection{wxSoundFileStream::Play}\label{wxsoundfilestreamplay} 56\func{bool}{Play}{\void} 57 58It starts playing the file. The playing begins, in background 59in nearly all cases, after the return of the function. The 60codec returns to a {\bf stopped} state when it reaches the 61end of the file. 62On success, it returns TRUE. 63 64\membersection{wxSoundFileStream::Record}\label{wxsoundfilestreamrecord} 65\func{bool}{Record}{\param{wxUint32 }{time}} 66 67It starts recording data from the sound stream and writing them 68to the output stream. You have to precise the recording length in 69parameter. This length is expressed in seconds. If you want to 70control the record length (using \helpref{Stop}{wxsoundfilestreamstop}), 71you can set it to wxSOUND\_INFINITE\_TIME. 72 73On success, it returns TRUE. 74 75\membersection{wxSoundFileStream::Stop}\label{wxsoundfilestreamstop} 76\func{bool}{Stop}{\void} 77 78It stops either recording or playing. Whatever happens (even unexpected 79errors), the stream is stopped when the function returns. When you are 80in recording mode, the file headers are updated and flushed if possible 81(ie: if the output stream is seekable). 82 83On success, it returns TRUE. 84 85\membersection{wxSoundFileStream::Pause}\label{wxsoundfilestreampause} 86\func{bool}{Pause}{\void} 87 88The file codec tries to pause the stream: it means that it stops audio 89production but keep the file pointer at the place. 90 91If the file codec is already paused, it returns FALSE. 92 93On success, it returns TREE. 94 95\membersection{wxSoundFileStream::Resume}\label{wxsoundfilestreamresume} 96\func{bool}{Resume}{\void} 97 98When the file codec has been paused using 99\helpref{Pause}{wxsoundfilestreampause}, you could be interrested in 100resuming it. This is the goal of this function. 101 102\membersection{wxSoundFileStream::IsStopped}\label{wxsoundfilestreamisstopped} 103\constfunc{bool}{IsStopped}{\void} 104 105It returns TRUE when the stream is stopped, in another case it returns 106FALSE. 107 108\membersection{wxSoundFileStream::IsPaused}\label{wxsoundfilestreamispaused} 109\constfunc{bool}{IsPaused}{\void} 110 111It returns TRUE when the stream is paused, in another case it returns 112FALSE. 113 114\membersection{wxSoundFileStream::StartProduction}\label{wxsoundfilestreamstartproduction} 115\func{bool}{StartProduction}{\param{int }{evt}} 116 117It is really not advised you call this function. From the wxSoundFileStream 118point of view it is an internal function. Internally, it is called after 119the file stream has been prepared to be played or to receive audio data and 120when it wants to start processing audio data. 121 122\membersection{wxSoundFileStream::StopProduction}\label{wxsoundfilestreamstopproduction} 123\func{bool}{StopProduction}{\void} 124 125As for \helpref{StartProduction}{wxsoundfilestreamstopproduction}, it is not 126advised for you to call this function. It is called by 127\helpref{Stop}{wxsoundfilestreamstop} when it needs to stop the audio data 128processing. 129 130\membersection{wxSoundFileStream::GetLength}\label{wxsoundfilestreamgetlength} 131\func{wxUint32}{GetLength}{\void} 132 133It returns the audio data length of the file stream. This length is expressed 134in bytes. If you need the length in seconds, you will need to use 135\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and 136\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}. 137 138\membersection{wxSoundFileStream::GetPosition}\label{wxsoundfilestreamgetposition} 139\func{wxUint32}{GetPosition}{\void} 140 141It returns the current position in the soundfile stream. The position 142is expressed in bytes. If you need the length in seconds, you will need to use 143\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and 144\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}. 145 146\membersection{wxSoundFileStream::SetPosition}\label{wxsoundfilestreamsetposition} 147\func{wxUint32}{SetPosition}{\param{wxUint32 }{new\_position}} 148 149It sets the current in the soundfile stream. The position 150 {\it new\_position} must be expressed in bytes. You can get 151a length/position in bytes from a time value using 152\helpref{GetSoundFormat}{wxsoundstreamgetsoundformat} and 153\helpref{GetTimeFromBytes}{wxsoundformatbasegettimefrombytes}. 154 155On success, it returns TRUE. 156 157\wxheading{Warning} 158 159Some wxStream may not be capable to support this function as 160it may not support the seekable functionnality. If this happens, 161it returns FALSE and leave the stream at the same position. 162 163\membersection{wxSoundFileStream::Read}\label{wxsoundfilestreamread} 164\func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}} 165 166You can obtain the audio data encoded in the file using this function. 167But it must be considered as an internal function. Used carelessly, it 168may corrupt the current state of the stream. 169Data are returned using in the original file coding (You must use a sound 170format object to decode it). 171 172\membersection{wxSoundFileStream::Write}\label{wxsoundfilestreamwrite} 173\func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}} 174 175You can put encoded audio data to the file using this function. 176But it must be considered as an internal function. Used carelessly, it 177may corrupt the current state of the stream. 178Data must be coded with the specified file coding (You must use a sound 179format object to do this). 180 181\membersection{wxSoundFileStream::SetSoundFormat}\label{wxsoundfilestreamsetsoundformat} 182\func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}} 183 184\membersection{wxSoundFileStream::GetCodecName}\label{wxsoundfilestreamgetcodecname} 185\constfunc{wxString}{GetCodecName}{\void} 186 187This function returns the Codec name. This is useful for those who 188want to build a player (But also in some other case). 189 190\membersection{wxSoundFileStream::CanRead}\label{wxsoundfilestreamcanread} 191\func{bool}{CanRead}{\void} 192 193You should use this function to test whether this file codec can read 194the stream you passed to it. 195 196\membersection{wxSoundFileStream::PrepareToPlay}\label{wxsoundfilestreampreparetoplay} 197\func{bool}{PrepareToPlay}{\void} 198 199It is called by wxSoundFileStream to prepare the specific file loader 200to prepare itself to play the file. Actually, this includes reading 201headers and setting the various parameters of the sound format. 202This should not be called by an external user but it should be 203implemented when you inherit wxSoundFileStream to build a new codec. 204 205It must return when the file is identified and the parameters have 206been set. In all other cases, you must return FALSE. 207 208\membersection{wxSoundFileStream::PrepareToRecord}\label{wxsoundfilestreampreparetorecord} 209\func{bool}{PrepareToRecord}{\param{wxUint32 }{time}} 210 211\membersection{wxSoundFileStream::FinishRecording}\label{wxsoundfilestreamfinishrecording} 212\func{bool}{FinishRecording}{\void} 213 214\membersection{wxSoundFileStream::RepositionStream}\label{wxsoundfilestreamrepositionstream} 215\func{bool}{RepositionStream}{\param{wxUint32 }{position}} 216 217This is called by wxSoundFileStream::SetPosition to seek the input stream 218to the right position. This must be overidden by the file codec class. 219The position is relative to the beginning of the samples. 220If it is impossible (as for a piped input stream), you must return FALSE. 221 222\membersection{wxSoundFileStream::FinishPreparation}\label{wxsoundfilestreamfinishpreparation} 223\func{void}{FinishPreparation}{\param{wxUint32 }{len}} 224 225This is an internal function but it must called by the file codec class when 226the "playing" preparation is finished and you know the size of the stream. 227If it is an {\it infinite} stream, you should set this to wxSOUND\_INFINITE\_TIME. 228 229\membersection{wxSoundFileStream::GetData}\label{wxsoundfilestreamgetdata} 230\func{wxUint32}{GetData}{\param{void* }{buffer}, \param{wxUint32 }{len}} 231 232This is called by wxSoundFileStream when it needs to get new sound data to 233send to the device driver (or to a conversion codec). This must be eventually 234overidden by the file codec class. The default behaviour is simply to read from 235the input stream. 236 237\membersection{wxSoundFileStream::PutData}\label{wxsoundfilestreamputdata} 238\func{wxUint32}{PutData}{\param{const void* }{buffer}, \param{wxUint32 }{len}} 239 240This is called by wxSoundFileStream when it needs to put new sound data received 241from the device driver (or from a conversion codec). This must be eventually 242overidden by the file codec class. The default behaviour is simply to write to 243the input stream. 244