/**************************************************************************** ** ** 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. */ /*! \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 QtMultimedia module. QtMultimedia 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 {qtmultimedia 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 \omit \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. \endomit \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). \target qtmultimedia 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 QtMultimedia 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. \section2 QML Video Example The \l {video/qmlvideo}{QML Video Example} demonstrates the various manipulations (move; resize; rotate; change aspect ratio) which can be applied to QML \l {VideoOutput} items. It also shows how native code can be combined with QML to implement more advanced functionality - in this case, C++ code is used to calculate the QML frame rate. This value is rendered in QML as a semi-transparent item overlaid on the video content. \section2 QML Video Shader Effects Example The \l {video/qmlvideofx}{QML Video Shader Effects Example} shows how the \l {ShaderEffect} element can be used to apply postprocessing effects, expressed in GLSL, to QML \l {VideoOutput} items. It re-uses the frame rate display code used by the \l {QML Video Example}. Finally, this application demonstrates the use of different top-level QML files to handle different physical screen sizes. On small-screen devices, menus are by default hidden, and only appear when summoned by a gesture. Large-screen devices show a more traditional layout in which menus are displayed around the video content pane. \section1 Reference documentation \section2 Main audio and video classes \annotatedlist multimedia \section2 Camera classes \annotatedlist camera \section2 Advanced usage. For developers wishing to access some platform specific settings, or to port the Qt Multimedia APIs to a new platform or technology, see \l{Multimedia Backend Development}. \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 */