path: root/doc/src/multimedia.qdoc

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/


/*!
    \group multimedia
    \title QtMobility Multimedia
    APIs to play and record media, and manage a collection of media content.
*/

// XXX title sucks
// XXX move backend stuff away
// XXX move QML stuff up
// XXX more introductory material
// XXX terminology
// XXX separate pages for audio, video, camera, radio, metadata
// control, mediaobject etc stuff
// symbian/harmattan specific pages

/*!

\page multimedia.html
\title Multimedia
\brief Provides a set of APIs to play and record media, and manage a
collection of media content.
\ingroup mobility

Multimedia provides a set of APIs that allow the developer to play, record
and manage a collection of media content. It is dependent on the
QtMultimediaKit module. QtMultimediaKit is the recommended API to build multimedia
applications using Qt. The Phonon API is no longer recommended.

\tableofcontents

\section1 No Special Namespace

Unlike the other APIs in QtMobility, the Multimedia API is \i not in the
\i QtMobility namespace.

\section1 Overview

This API delivers an easy to use interface to multimedia functions. The
developer can use the API to display an image, or a video, record sound or play a
multimedia stream.

There are several benefits this API brings to Qt. Firstly, the
developer can now implement fundamental multimedia functions with minimal
code, mostly because they are already implemented. Also there is a great
deal of flexibility with the media source or the generated multimedia. The
source file does not need to be local to the device, it could be streamed
from a remote location and identified by a URL. Finally, many different
codecs are supported 'out
of the box'.

The supplied \l {qtmultimediakit examples}{examples} give a good idea at the ease of use of the API. When
the supporting user interface code is ignored we can see that functionality
is immediately available with minimal effort.

\section2 Audio

The Audio Recorder example is a good introduction to the basic use of the API. We will use snippets from this example to illustrate how to use the
API to quickly build functionality.

The first step is to demonstrate recording audio to a file. When recording from an audio source there are a number of things we may want to control beyond the essential user interface. We may want a particular encoding of the file, MP3 or Ogg Vorbis for instance, or select a different input source. The user may modify the bitrate, number of channels, quality and sample rate. Here the example will only modify the codec and the source device, since they are essential.

To begin, the developer sets up a source and a recorder object. A
\l{QAudioCaptureSource} object is created and used to initialize a \l{QMediaRecorder} object. The output file name is then set for the \l{QMediaRecorder} object.

\code
    audiosource = new QAudioCaptureSource;
    capture = new QMediaRecorder(audiosource);

    capture->setOutputLocation(QUrl("test.raw"));
\endcode

A list of devices is needed so that an input can be selected in the user interface

\code
    for(int i = 0; i < audiosource->deviceCount(); i++)
        deviceBox->addItem(audiosource->name(i));
\endcode

and a list of the supported codecs for the user to select a codec,

\code
    QStringList codecs = capture->supportedAudioCodecs();
    for(int i = 0; i < codecs.count(); i++)
        codecsBox->addItem(codecs.at(i));
\endcode

To set the selected device or codec just use the index of the device or codec by calling the setter in \i {audiosource} or \i {capture} as appropriate, for example,

\code
    audiosource->setSelectedDevice(i);
    ...
    capture->setAudioCodec(codecIdx);
\endcode

Now start recording by using the \l {QMediaRecorder}{record()} function from the new \l{QMediaRecorder} object

\code
    capture->record();
\endcode

And stop recording by calling the matching function \l {QMediaRecorder::stop()}{stop()} in \l{QMediaRecorder}.

\code
    capture->stop();
\endcode

How then would this audio file be played? The \l {QMediaPlayer} class will be
used as a generic player. Since the player can play both video and audio files the interface will be more complex, but for now the example will concentrate on the audio aspect.

Playing the file is simple: create a player object, pass in the filename, set
the volume or other parameters, then play. Not forgetting that the code will
need to be hooked up to the user interface.

\code
    QMediaPlayer *player = new QMediaPlayer;
    ...
    player->setMedia(QUrl::fromLocalFile("test.raw"));
    player->setVolume(50);
    player->play();
\endcode

The filename does not have to be a local file. It could be a URL to a
remote resource. Also by using the \l{QMediaPlaylist} class from this API
we can play a list of local or remote files. The \l{QMediaPlaylist}
class supports constructing, managing and playing playlists.

\code
    player = new QMediaPlayer;

    playlist = new QMediaPlaylist(player);
    playlist->addMedia(QUrl("http://example.com/myfile1.mp3"));
    playlist->addMedia(QUrl("http://example.com/myfile2.mp3"));
    ...
    playlist->setCurrentPosition(1);
    player->play();
\endcode

To manipulate the playlist there are the usual management functions (which are in fact slots): previous, next, setCurrentPosition and shuffle. Playlists can be built, saved and loaded using the API.



\section2 Video

Continuing with the example discussed for an Audio recorder/player, we can use this to show how to play video files with little change to the code.

Moving from audio to video requires few changes in the sample code. To play a
video playlist the code can be changed to include another new QtMobility
Project class: \l{QVideoWidget}. This class enables control of a video
resource with signals and slots for the control of brightness, contrast,
hue, saturation and full screen mode.

\code
    player = new QMediaPlayer;

    playlist = new QMediaPlaylist(player);
    playlist->addMedia(QUrl("http://example.com/myclip1.mp4"));
    playlist->addMedia(QUrl("http://example.com/myclip2.mp4"));
    ...
    widget = new QVideoWidget(player);
    widget->show();

    playlist->setCurrentPosition(1);
    player->play();
\endcode

The \l {player}{Player} example does things a bit differently to our sample
code. Instead of using a QVideoWidget object directly, the Player example
has a \i {VideoWidget} class that inherits from QVideoWidget. This means
that functions can be added to provide functions such as full screen display,
either on a double click or on a particular keypress.

\snippet ../../demos/player/player.cpp  2


\section2 Radio

QRadioTunerControl is a pure virtual base class that will be the basis for
any platform specific radio device control. When the functions are
implemented the developer will be able to quickly produce an application
that supports the typical uses of an FM radio including tuning, volume,
start, stop and various other controls.

\section1 Extending the API for Symbian and Maemo


For the developer who wishes to extend the functionality of the Multimedia
classes there are several classes of particular importance. The default
classes are QMediaService, QMediaServiceProvider and QMediaControl.

Basically, the idea is that to use the Multimedia API you would use these
three classes or classes derived from them as follows

    \list
    \o \l QMediaServiceProvider is used by the top level client class to request a service. The top level class knowing what kind of service it needs.

    \o \l QMediaService provides a service and when asked by the top level object, say a component, will return a QMediaControl object.

    \o \l QMediaControl allows the control of the service using a known interface.
    \endlist

Consider a developer creating, for example, a media player class called MyPlayer.
It may have special requirements beyond ordinary media players and so may
need a custom service and a custom control. We can subclass \l QMediaServiceProvider
to create our MyServiceProvider class. Also we will create a
MyMediaService, and the MyMediaControl to manipulate the media service.

The MyPlayer object calls MyServiceProvider::requestService() to get an
instance of MyMediaService. Then the MyPlayer object calls this service
object it has just received and calling \l {QMediaService::requestControl()}{requestControl()}
it will receive the control object derived from QMediaControl. Now we have
all the parts necessary for our media application. We have the service
provider, the service it provides and the control used to manipulate the
service. Since our MyPlayer object has instances of the service and its
control then it would be possible for these to be used by associated classes
that could do additional actions, perhaps with their own control since the
parameter to requestControl() is a c-type string, \i {const char *}, for the
interface.


\section2 Adding a Media Service Provider

The base class for creating new service providers is \l{QMediaServiceProvider}.
The user must implement the \l{QMediaServiceProvider::requestService()}{requestService()}
function

\code
    QMediaService* requestService(const QByteArray &type, const QMediaServiceProviderHint &hint);
\endcode

The details of implementation will depend on the provider. Looking at the
class \l QMediaServiceProvider for the default implementation. Notice that
\l {QMediaServiceProvider::requestService()}{requestService()} uses the
\l QMediaServiceProviderHint to look for the appropriate plugin and then to
insert it into the plugin map. However, for a specific service provider there
is probably no need for this approach, it will simply depend on what the
developer wants to implement.

Other methods that may be overloaded
\code
    void releaseService(QMediaService *service);

    QtMediaServices::SupportEstimate hasSupport(const QByteArray &serviceType,
                                        const QString &mimeType,
                                        const QStringList& codecs,
                                        int flags) const;

    QStringList supportedMimeTypes(const QByteArray &serviceType, int flags) const;

    QList<QByteArray> devices(const QByteArray &serviceType) const;

    QString deviceDescription(const QByteArray &serviceType, const QByteArray &device);
\endcode

The choice of what needs to be done depends on what the developer wishes to do with the service.


\section1 Camera Support

Creating still images and video.

\section2 Still Images

In order to capture an image we need to create a \l QCamera object and use
it to initialize a \l QVideoWidget, so we can see where the camera is
pointing - a viewfinder. The camera object is also used to initialize a new
QCameraImageCapture object, \i imageCapture. All that is then needed is to start
the camera, lock it so that the settings are not changed while the image
capture occurs, capture the image, and finally unlock the camera ready for
the next photo.

    \code
            camera = new QCamera;
            viewFinder = new QCameraViewfinder();
            viewFinder->show();

            camera->setViewfinder(viewFinder);

            imageCapture = new QCameraImageCapture(camera);

            camera->setCaptureMode(QCamera::CaptureStillImage);
            camera->start();

            //on half pressed shutter button
            camera->searchAndLock();

            ...

            //on shutter button pressed
            imageCapture->capture();

            //on shutter button released
            camera->unlock();
    \endcode

\note Alternatively, we could have used a QGraphicsVideoItem as a viewfinder.


\section2 Video Clips

Previously we saw code that allowed the capture of a still image. Recording
video requires the use of a \l QMediaRecorder object and a \l
QAudioCaptureSource for sound.

To record video we need a camera object, as before, a media recorder and a
viewfinder object. The media recorder object will need to be initialized.

    \code
    camera = new QCamera;
    mediaRecorder = new QMediaRecorder(camera);

    camera->setCaptureMode(QCamera::CaptureVideo);
    camera->start();

    //on shutter button pressed
    mediaRecorder->record();
    \endcode

Signals from the \i mediaRecorder can be connected to slots to react to
changes in the state of the recorder or error events. Recording itself
starts with the \l {QMediaRecorder::record()}{record()} function of
mediaRecorder being called, this causes the signal \l
{QMediaRecorder::stateChanged()}{stateChanged()} to be emitted. The
recording process can be changed with the \l {QMediaRecorder::record()}{record()},
\l {QMediaRecorder::pause()}{pause()}, \l {QMediaRecorder::stop()}{stop()} and
\l {QMediaRecorder::setMuted()}{setMuted()} slots in \l QMediaRecorder.

When the camera is in video mode, as decided by the application, then as the
shutter button is pressed the camera is locked as before but instead the
\l {QMediaRecorder::record()}{record()} function in \l QMediaRecorder is used.



\section2 Focus

Focusing is managed by the classes \l QCameraFocus and \l QCameraFocusControl.
QCameraFocus allows the developer to set the general policy by means of the
enums for the \l {QCameraFocus::FocusMode}{FocusMode} and the
\l {QCameraFocus::FocusPointMode}{FocusPointMode}.
\l {QCameraFocus::FocusMode}{FocusMode} deals with
settings such as \l {QCameraFocus::FocusMode}{AutoFocus},
\l {QCameraFocus::FocusMode}{ContinuousFocus} and
\l {QCameraFocus::FocusMode}{InfinityFocus}, whereas
\l {QCameraFocus::FocusPointMode}{FocusPointMode} deals with the various focus zones within the view.
\l {QCameraFocus::FocusPointMode}{FocusPointMode} has support for face
recognition, center focus and a custom focus where the focus point can be specified.



\section2 Canceling Asynchronous Operations

Various operations such as image capture and auto focusing occur
asynchrously. These operations can often be cancelled by the start of a new
operation as long as this is supported by the backend. For image capture,
the operation can be cancelled by calling
\l {QCameraImageCapture::cancelCapture()}{cancelCapture()}. For \l {QCameraFocus::FocusMode}{auto-focus},
\l {QCameraExposure::ExposureMode}{auto-exposure} or \l {QCameraImageProcessing::WhiteBalanceMode}{white balance}
cancellation can be done by calling \l {QCamera::unlock()}{unlock}(QCamera::LockFocus).



\section2 Camera Controls

    \table
        \header
            \o Control Name
            \o Description
        \row
            \o camera
            \o The interface for system camera devices
        \row
            \o exposure
            \o Includes: flash mode; flash power; metering mode; aperture; shutter speed, iso setting
        \row
            \o focus
            \o Includes: optical zoom; digital zoom; focus point; focus zones
        \row
            \o image processing
            \o White balance; contrast; saturation; sharpen; denoise
        \row
            \o locks
            \o Handles the locking and unlocking of camera devices
    \endtable


\section2 Classes
\annotatedlist camera




\target qtmultimediakit examples
\section1 Examples

\section2 Record a Sound Source

\l{audiorecorder}{AudioRecorder} is a demonstration of the discovery of
the supported devices and codecs and the use of recording functions in the
QMediaRecorder class.

\section2 Play a Media File

The \l{player}{Player} example is a simple multimedia player. Select a
video file to play, stop, pause, show in fullscreen or manipulate various
image attributes using the Color Options button.

\section2 Slide Show

The \l{slideshow}{Slide Show} shows the use of the QMediaImageViewer and
QVideoWidget classes.

\section2 Camera Example

The \l{Camera Example} shows how use the QtMultimediaKit API to quickly
write a camera application in C++.

\section2 QML Camera Example

The \l {QML Camera Example} demonstrates still image capture and controls
using the QML plugin. Video recording is not currently available.


\section1 Reference documentation

\section2 Main classes

\annotatedlist multimedia


\section2 Classes for service implementers.

\annotatedlist multimedia-serv

\section2 QML Elements
\list
\o \l {SoundEffect}{SoundEffect: Low Latency Sound Effects}
\o \l {Audio}{Audio: Music playback}
\o \l {Video}{Video: Video playback}
\endlist
*/