Qt API | Qtopia API | Qtopia Documentation |

# MediaRecorderEncoder Class Reference

The MediaRecorderEncoder class provides an abstract base class for Qtopia MediaRecorder encoder plugins. More...

`#include <qtopia/mediarecorderplugininterface.h>`

List of all member functions.

## Public Members

- virtual ~MediaRecorderEncoder ()
- virtual int pluginNumFormats () const = 0
- virtual QString pluginFormatName ( int format ) const = 0
- virtual QString pluginFormatTag ( int format ) const = 0
- virtual QString pluginComment () const = 0
- virtual double pluginVersion () const = 0
- virtual QString pluginMimeType () const = 0
- virtual bool begin ( QIODevice * device, const QString & formatTag ) = 0
- virtual bool end () = 0
- virtual bool isActive () const = 0
- virtual bool setAudioChannels ( int channels ) = 0
- virtual bool setAudioFrequency ( int frequency ) = 0
- virtual bool writeAudioSamples ( const short * samples, long numSamples ) = 0
- virtual bool addComment ( const QString & tag, const QString & contents ) = 0
- virtual long estimateAudioBps ( int frequency, int channels, const QString & formatTag ) = 0
- virtual bool supportsAudio () const = 0
- virtual bool supportsVideo () const = 0
- virtual bool supportsComments () const = 0
- virtual bool requiresDirectAccess () const = 0

## Detailed Description

The MediaRecorderEncoder class provides an abstract base class for Qtopia MediaRecorder encoder plugins.

Writing an encoder plugin is achieved by subclassing this base class, reimplementing the pure virtual functions and exporting the class with the `Q_EXPORT_PLUGIN` macro. See the Plugins documentation for details.

The functions in this class are typically used in the following order when recording audio:

      begin(device, tag);
      addComment("name", "value");
      ...
      addComment("name", "value");
      setAudioChannels(2);
      setAudioFrequency(44100);
      writeAudioSamples(samples, numSamples);
      ...
      writeAudioSamples(samples, numSamples);
      end();

See also QIODevice, MediaRecorderPluginInterface, begin() and Qtopia Classes.

## Member Function Documentation

### MediaRecorderEncoder::~MediaRecorderEncoder ()`[virtual]`

Destructs a MediaRecorderEncoder.

### bool MediaRecorderEncoder::addComment ( const QString & tag, const QString & contents )`[pure virtual]`

Adds a comment string contents tagged as tag to the recorded output. The plugin may ignore tags that it doesn't understand.

Returns TRUE if the comment was successfully added (or ignored). Returns FALSE if not recording or the data header has already been written.

The data header is considered written upon the first call to write audio samples. This is true even if plugin's data format places comments at the end of the stream, rather than the front. The plugin should cache the comments until it is ready to output them.

This should only be called if comments are supported by the plugin.

See also begin(), writeAudioSamples() and supportsComments().

### bool MediaRecorderEncoder::begin ( QIODevice * device, const QString & formatTag )`[pure virtual]`

Begin recording on the specified output device, which must be capable of direct access (seeking) if MediaRecorderEncoder::requiresDirectAccess() returns TRUE. formatTag selects which format to use.

Returns TRUE if recording has begun. Returns FALSE if recording is already in progress or if device is not capable of seeking.

This call will typically be followed by calls to set the channels, frequency, and file comments.

See also setAudioChannels(), setAudioFrequency(), addComment(), writeAudioSamples() and requiresDirectAccess().

### bool MediaRecorderEncoder::end ()`[pure virtual]`

End recording on the current output device. This function may back-patch earlier bytes in the output. Once it has finished outputting the data, it will leave the device positioned after all bytes that were written.

Returns TRUE if recording was successfully terminated. Returns FALSE if not currently recording, or there was an error writing to the device.

### long MediaRecorderEncoder::estimateAudioBps ( int frequency, int channels, const QString & formatTag )`[pure virtual]`

Estimate the number of bytes per second that are needed to record audio in the formatTag format at a given frequency with the specified number of channels.

### bool MediaRecorderEncoder::isActive () const`[pure virtual]`

Returns TRUE if the recorder is currently active; FALSE otherwise.

### QString MediaRecorderEncoder::pluginComment () const`[pure virtual]`

Returns a comment that describes the purpose of the plugin.

### QString MediaRecorderEncoder::pluginFormatName ( int format ) const`[pure virtual]`

Returns the name of one of a plugin's data format, e.g. "Wav Format". The data format is selected using format as an index. The name may be displayed to the user in a list of supported recording formats.

### QString MediaRecorderEncoder::pluginFormatTag ( int format ) const`[pure virtual]`

Returns the tag name of a plugin's data format. For example, "pcm". The data format is selected using format as an index. This value is used with MediaRecorderEncoder::begin .

### QString MediaRecorderEncoder::pluginMimeType () const`[pure virtual]`

Returns the MIME type for the plugin's recommended file extension, e.g. `audio/x-wav`

### int MediaRecorderEncoder::pluginNumFormats () const`[pure virtual]`

Returns the number of formats that are supported by this plugin.

### double MediaRecorderEncoder::pluginVersion () const`[pure virtual]`

Returns the version of the plugin. Normally 1.0.

### bool MediaRecorderEncoder::requiresDirectAccess () const`[pure virtual]`

Returns TRUE if this plugin must be supplied a direct access (seekable) output device.

See also begin().

### bool MediaRecorderEncoder::setAudioChannels ( int channels )`[pure virtual]`

Sets the number of audio channels in the recorded data to either 1 or 2.

Returns TRUE if the channel count was set successfully. Returns FALSE if not recording, the data header has already been written, or if channels is neither 1 nor 2.

The data header is considered written upon the first call to write audio samples.

See also begin(), setAudioFrequency() and writeAudioSamples().

### bool MediaRecorderEncoder::setAudioFrequency ( int frequency )`[pure virtual]`

Sets the audio sample frequency in the recorded data.

Returns TRUE if the frequency was set successfuly. Returns FALSE if not recording, the data header has already been written, or if frequency is less than or equal to zero.

The data header is considered written upon the first call to write audio samples.

See also begin(), setAudioChannels() and writeAudioSamples().

### bool MediaRecorderEncoder::supportsAudio () const`[pure virtual]`

Returns TRUE if this plugin supports audio; FALSE otherwise.

### bool MediaRecorderEncoder::supportsComments () const`[pure virtual]`

Returns TRUE if this plugin supports comments; FALSE otherwise.

See also addComment().

### bool MediaRecorderEncoder::supportsVideo () const`[pure virtual]`

Returns TRUE if this plugin supports video; FALSE otherwise.

### bool MediaRecorderEncoder::writeAudioSamples ( const short * samples, long numSamples )`[pure virtual]`

Writes a buffer of audio samples to the recorded output.

Samples are assumed to always be 16-bit and in host byte order. It is the responsibility of the caller to rescale other sample sizes.

The numSamples value is the number of 16-bit quantities in the samples buffer. This will be a multiple of two for stereo data, with alternating channel samples.

Returns TRUE if the samples were successfully written. Returns FALSE if not recording or there was an error writing to the output device.

See also begin(), setAudioChannels() and setAudioFrequency().

This file is part of the Qtopia , copyright © 1995-2002 Trolltech, all rights reserved.