AudioRecorder

Since: BlackBerry 10.0.0

#include <bb/multimedia/AudioRecorder>

To link against this class, add the following line to your .pro file: LIBS += -lbbmultimedia

The AudioRecorder class provides the ability to record audio.

A recording example in C++:

        bb::multimedia::AudioRecorder recorder;
        recorder.setOutputUrl("file:///accounts/1000/shared/voice/recording.m4a");
        recorder.record();
        ...
        recorder.reset();

A recording example in QML:

    import bb.multimedia 1.0
    // ...

    Page {
        Container {
            // ...
            attachedObjects: [
                AudioRecorder {
                    id: audioRecorder
                    outputUrl: "file:///accounts/1000/shared/voice/recording.m4a"
                }
            ]

            Button {
                id: btnRecord
                text: "Record"
                onClicked: {
                    audioRecorder.record();
                }
            }

            Button {
                id: btnStopRecord
                text: "Stop Recording"
                onClicked: {
                    audioRecorder.reset();
                }
            }
        }
    }
Permissions:

The application must have the record_audio permission to access the microphone on the device. No other special permission is needed to record to a file in the application sandbox. Recording to the shared content area on the device would require the access_shared permission.


Overview

Signals Index

voidaudioChannelConfigurationChanged (bb::multimedia::AudioChannelConfiguration::Type audioChannelConfiguration)
voidaudioManagerHandleChanged (unsigned int audioManagerHandle)
voiddurationChanged (unsigned int duration)
voiderror (bb::multimedia::MediaError::Type mediaError, unsigned int position)
voidmediaStateChanged (bb::multimedia::MediaState::Type mediaState)
voidrecordingLevelChanged (double percentage)
voidstatusIntervalChanged (unsigned int statusInterval)

Properties

bb::multimedia::AudioChannelConfiguration::Type audioChannelConfiguration

Represents the audio channel configuration.

Since:

BlackBerry 10.3.1

QVariant audioManagerHandle

Represents the handle of an externally managed audio manager.

Since:

BlackBerry 10.0.0

bb::multimedia::DeviceMode::Type deviceMode[read-only]

Represents the device mode of the recorder.

Since:

BlackBerry 10.3.1

QVariant duration[read-only]

Represents the length of the audio recording.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type mediaError[read-only]

Represents the last runtime error code that was emitted from the error() signal.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaState::Type mediaState[read-only]

Represents the current media state.

Since:

BlackBerry 10.0.0

QUrl outputUrl

Represents the output URL that will be used to store the audio recording.

Since:

BlackBerry 10.0.0

QVariant statusInterval

Represents the requested amount of time in milliseconds between regular status updates.

Generally this setting is applied to duration signals.

Since:

BlackBerry 10.0.0

Public Functions

AudioRecorder (

AudioRecorder class constructor.

Parameters
parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.0.0

virtual~AudioRecorder ()

Destructor.

Since:

BlackBerry 10.0.0

bb::multimedia::AudioChannelConfiguration::Type audioChannelConfiguration ()

Returns the audio channel configuration.

Return:

Returns the audio channel configuration value.

Since:

BlackBerry 10.3.1

unsigned int audioManagerHandle ()

Returns the handle of an externally managed audio manager.

Return:

Returns the handle of an externally managed audio manager or zero if managed internally.

Since:

BlackBerry 10.0.0

bb::multimedia::DeviceMode::Type deviceMode ()

Retrieves the device mode for the recorder.

Since:

BlackBerry 10.3.1

unsigned int duration ()

Provides the duration of the current recording.

The duration is available once prepare() has been successfully called. The duration is no longer available once stop() has been called. In any other case, a duration of zero is returned.

Return:

Returns the duration of the current recording in milliseconds once determined, and zero otherwise.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type mediaError ()

Used to retrieve the last recording error.

If the error() signal has been emitted, this property will return the last error type, otherwise MediaError::None is returned. This property is automatically reset to MediaError::None when recording starts.

Return:

Returns the last recording error.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaState::Type mediaState ()

Used to determine the current media state.

MediaState::Unprepared is returned when prepare() has not been called, or if the recording has been stopped. When recording, MediaState::Started is returned. When paused, MediaState::Paused is returned.

Return:

Returns the current media state.

Since:

BlackBerry 10.0.0

QUrl outputUrl ()

Retrieves the output URL.

This function retrieves the URL, as an absolute path, for the output of the recorder. An empty QUrl is returned when setOutputUrl() has not been called.

Return:

Returns the URL, as an absolute path, for the output of the recording, or an empty QUrl if setOutputUrl() has not been called.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type setAudioManagerHandle (
  • unsigned intaudioManagerHandle)

Sets the handle of an externally managed audio manager.

Changing this property while the recorder is prepared will cause the player to unprepare. Setting an audio manager handle of zero will reset to the default audio manager. The original owner of the audio manager handle is responsible for releasing it.

Parameters
audioManagerHandle

The audio manager handle to use.

Return:

Returns the last recording error.

Since:

BlackBerry 10.0.0

unsigned int statusInterval ()

Represents the requested amount of time in milliseconds between regular status updates.

Generally this setting is applied to duration updates. By default the requested update status interval is 1000 milliseconds.

Return:

Returns the current requested status interval in milliseconds, as described by setStatusInterval().

Since:

BlackBerry 10.0.0

Public Slots

bb::multimedia::MediaError::Type pause ()

Pauses the recording.

On success, a paused() signal is emitted. Call record() to restart recording.

Calling this function while recording is already paused does nothing.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type prepare ()

Acquires the necessary resources for recording without recording the track.

This process will move the recorder into the prepared state. A mediaStateChanged signal with a parameter value of for the recording. If the recorder is already prepared, this call does nothing.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type record ()

Starts recording to the output.

This function will start the recording. The recorder will acquire the necessary resources for recording, and emit a prepared() signal. A recording() signal is emitted while recording.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type reset ()

Releases any resources that are currently held by the recorder, and moves the recorder into the unprepared state.

This function will release all resources held by the recorder, and result in a mediaStateChanged() signal being emitted notifying of the unprepared state. This signal indicates that the recorder is no longer in possession of the resources required to record.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type setAudioChannelConfiguration (

Sets audio channel configuration to use for recording.

If recording is active when this configuration is set the current recording will stop. When record() is called again the new audio channel configuration will be used.

Parameters
audioChannelConfiguration

The requested audio channel configuration to use.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.3.1

void setOutputUrl (

Used to set the output location for the recording.

The QUrl should point to the location of a local file. This function must be called before calling the prepare() function.

Parameters
url

The output location of the audio recording.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type setStatusInterval (
  • unsigned intstatusInterval)

Sets the requested amount of time in milliseconds between regular status updates.

Generally this setting is applied to duration signals.

Parameters
statusInterval

The requested status interval in milliseconds.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.0.0

Signals

void audioChannelConfigurationChanged (

This signal is emitted when the audio channel configuration value is changed.

Parameters
audioChannelConfiguration

The requested audio channel configuration to use.

Since:

BlackBerry 10.3.1

void audioManagerHandleChanged (
  • unsigned intaudioManagerHandle)

This signal is emitted when the externally managed audio manager has changed.

Parameters
audioManagerHandle

The audio manager handle.

Since:

BlackBerry 10.0.0

void durationChanged (
  • unsigned intduration)

This signal is emitted when the track duration is known.

When a track is changed, the duration of that track is not known immediately. This signal is emitted when the duration of the tracks is available.

Parameters
duration

The duration of the track in milliseconds.

Since:

BlackBerry 10.0.0

void error (

This signal is emitted when an error occurs during any operation on the AudioRecorder.

When an error occurs during a recording, this signal is emitted with the error code, as well as the position in the recording where the error occurred.

Parameters
mediaError

The recording media error.

position

The position of the recorder where the error occurred.

Since:

BlackBerry 10.0.0

void mediaStateChanged (

This signal is emitted when the state of the media has been changed.

Parameters
mediaState

The current media state.

Since:

BlackBerry 10.0.0

void recordingLevelChanged (
  • doublepercentage)

This signal is emitted when the level of content being recorded changes.

This is a percentage of the total volume available to the recording. For example, if the sound input to the microphone is loud while recording, then this value will be high. If the sound input to the microphone is quiet while recording, then this value will be low.

Parameters
percentage

The sound input volume expressed as a value between 0.0 and 1.0 where 0.0 is silent and 1.0 is the maximum sound input.

Since:

BlackBerry 10.0.0

void statusIntervalChanged (
  • unsigned intstatusInterval)

This signal is emitted when the requested status interval has been changed.

This signal is emitted in response to a call to setStatusInterval().

Parameters
statusInterval

The requested status interval in milliseconds.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus