<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-F9896E96-1076-552D-AE54-8F9DABED867F"><title>Configuring the Video Player</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to configure the video player. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to make configuration adjustments to the video player. </p> <p><b>Required Background</b> </p> <p>The <xref href="GUID-2DC80BA9-7AA2-5CD3-9105-1DE28CE196C1.dita">Video Client Overview</xref> introduces the video client utilities. </p> <p><b>Introduction</b> </p> <p>The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref> class. The video data can be supplied either in a file, a descriptor or a URL. </p> </section> <section><title>Using Video Player </title> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-0A783BCE-7C87-5EE1-BFDA-BD2847CF1E4F"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-18902F43-1F13-5A91-84AD-94732560A554">Set the Display Window</xref>  </p> </li> <li id="GUID-4A64B04C-737D-587E-BBA4-478EE453EC82"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-CDD3561D-84E4-5524-9593-5055659B6CB0"> Query and Set the Volume</xref>  </p> </li> <li id="GUID-15F0C370-6460-5D6D-8CDB-B042CBD4A7C6"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-BBCD720C-1276-5D6C-B9E6-1946EE019987">Query and Set the Balance</xref>  </p> </li> <li id="GUID-ACB66213-E77F-5F93-BF2D-A7DEECFA10D1"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-7666501B-196B-5FE9-A331-311B11BF7954">Query and Set the Priority</xref>  </p> </li> <li id="GUID-7E7ACD89-0ECB-5CD7-A550-571BC8F8FE1C"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-8B88F87D-A3F0-5521-92DA-C74EE2D942A8">Query and Set the Bit and Frame Rate</xref>  </p> </li> <li id="GUID-1ED08DD8-4D68-52AF-89DA-7617BCE9A388"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-7D998004-DC09-5328-B2EE-AA363FB2D1C5">Query and Set the Current Playback Position</xref>  </p> </li> <li id="GUID-ADFC9AEB-30BE-56A0-B2C0-F6F2E7D12C2E"><p><xref href="GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita#GUID-F9896E96-1076-552D-AE54-8F9DABED867F/GUID-0A67AED6-860A-5D84-9CE3-6E30A673DD82">Query and Set the MIME and Codec Type</xref>  </p> </li> </ul> <p id="GUID-18902F43-1F13-5A91-84AD-94732560A554"><b>Setting the Display Window</b> </p> <p>The high level steps to set the display window are shown here: </p> <ul><li id="GUID-86A3CE74-3BC6-5C40-B9D4-9A6D89C2D059"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-34881891-A618-3E46-B6E2-3BA63324C0D7"><apiname>CVideoPlayerUtility::SetDisplayWindowL</apiname></xref>: This is used to provide the video controller with an area of display to render the current video frame. It can be represented pictorially as shown below: </p> <fig id="GUID-FAA210BE-66AB-5B23-AD33-F623B30AE305"><title>

                     Video display regions 

                  </title> <image href="GUID-1E25EE44-9421-549C-B79E-AEFE87308011_d0e311449_href.png" placement="inline"/></fig> <p>The screeenRect specifies the area within the window provided for displaying the video image. This rectangle is in screen coordinates. The video frame will be fitted to this rectangle as best possible, while maintaining the original aspect ratio. </p> <p>The ClipRect specifies the region to draw. The drawn region will be the intersection between the ClipRect and the ScreenRect. </p> <p>A crop region is defined as a region in the source video frame. The cropped region is displayed in the center of the ScreenRect with the same scaling as if it was displayed as part of the whole image. This could be used to zoom in on a region by setting the crop region, and setting the scale factor to fill the WindowRect. </p> <codeblock id="GUID-3F331C91-F37E-5575-9994-A162E3C88EAD" xml:space="preserve">void CPlayVideo::SetDisplayWindowL(RWsSession &amp;aWs, CWsScreenDevice &amp;aScreenDevice, RWindowBase &amp;aWindow, const TRect &amp;aWindowRect, const TRect &amp;aClipRect)

    {

    iVideoUtility->SetDisplayWindowL(aWs, aScreenDevice, aWindow, aWindowRect, aClipRect);

    }

</codeblock> </li> </ul> <p id="GUID-CDD3561D-84E4-5524-9593-5055659B6CB0"><b>Querying and Setting the Volume</b> </p> <p>The current volume settings can be reported and set appropriately with the help of the following functions: : </p> <ul><li id="GUID-E8AFCF73-2B6E-5DF1-80EE-69B2E7D51260"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-4397F487-2C26-3F6C-B347-F58C0F8E1DB4"><apiname>CVideoPlayerUtility::Volume()</apiname></xref>: Returns the current playback volume for the audio track of the video clip. </p> <codeblock id="GUID-F4994952-BDBA-51D6-B1C5-6658EE4C31A5" xml:space="preserve">TInt CPlayVideo::Volume() 

    {

    return iVideoUtility->Volume();

    }</codeblock> </li> <li id="GUID-4C860E43-36B7-58C3-820A-E5901C7B250C"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-842870F6-2A0E-36B2-8ADB-41CE032DCF85"><apiname>CVideoPlayerUtility::MaxVolume()</apiname></xref>: Returns the maximum volume that the audio track can support. </p> </li> <li id="GUID-BEEFF82A-D825-512C-86BF-EA2E5B55F48E"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-3B55A392-FD48-30FD-8038-405366EB241C"><apiname>CVideoPlayerUtility::SetVolumeL()</apiname></xref>: This function allows the volume of the audio track of the video clip to be set. The volume can be changed before or during playback and comes to effect immediately. The volume can be set to a value anywhere between zero and the maximum permissible volume. </p> <codeblock id="GUID-F1ACB4E4-672E-58A1-8C42-F6BC6EB70774" xml:space="preserve">TInt volume;

volume = iVideoPlayer.MaxVolume(); \\Returns maximum volume

void CPlayVideo::SetVolumeL(TInt aVolume) \\Set the audio volume

    {

    iVideoUtility->SetVolumeL(aVolume);

    } 

//The volume must be a value between 0 and the value returned by the MaxVolume function.

</codeblock> </li> </ul> <p id="GUID-BBCD720C-1276-5D6C-B9E6-1946EE019987"><b>Querying and Setting the Balance</b> </p> <p>The audio playback balance settings can be done using the following functions: </p> <ul><li id="GUID-D5970FD6-C545-54AD-A3C4-6710C7A744ED"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-AF2BEB2A-ED31-3671-B479-2027B9EBA5A6"><apiname>CVideoPlayerUtility::SetBalanceL()</apiname></xref>: This function sets the current playback balance for the audio track of the video clip. It can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight. </p> <codeblock id="GUID-A675CCAF-EFD5-599C-BB5A-3756E49E0F5E" xml:space="preserve">void CPlayVideo::SetBalanceL(TInt aBalance)

    {

    iVideoUtility->SetBalanceL(aBalance);

    }</codeblock> </li> <li id="GUID-9AE78FF2-9210-5027-BE63-7FA63EFE5116"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-1E3592A8-6C90-3F2F-95A5-F0908ECE1B7B"><apiname>CVideoPlayerUtility::Balance()</apiname></xref>: This function returns the current playback balance settings for the audio track of the video clip. </p> <codeblock id="GUID-AE730785-2C00-5738-9490-34EB2E04025B" xml:space="preserve">TInt CPlayVideo::Balance() 

    {

    return iVideoUtility->Balance();    

    }</codeblock> </li> </ul> <p id="GUID-7666501B-196B-5FE9-A331-311B11BF7954"><b>Querying and Setting the Priority</b> </p> <p>To set the priority for the playback to access the sound hardware, use the following methods: </p> <ul><li id="GUID-8573BEA1-DBE1-5AA2-8329-853B6B5BDD50"><p> <xref href="GUID-E03EA458-1ABD-34A4-BBB2-F3C65D035773.dita"><apiname>PriorityL()</apiname></xref>: This function returns the current playback priority. This is used to arbitrate between multiple objects simultaneously trying to accesses the sound hardware. </p> </li> <li id="GUID-B7B7769A-DAE7-503F-8375-6D99AABE9596"><p> <xref href="GUID-3A818B04-A01A-35EB-9F6C-E13543B54CB1.dita"><apiname>SetPriorityL()</apiname></xref>: This function sets the playback priority. </p> <codeblock id="GUID-C8835378-FEF4-5E36-981B-A8E8B55B7FDE" xml:space="preserve">void CPlayVideo::SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref)

    {

    iVideoUtility->SetPriorityL(aPriority, aPref);

    }</codeblock> </li> </ul> <p id="GUID-8B88F87D-A3F0-5521-92DA-C74EE2D942A8"><b>Querying and Setting the Bit and Frame Rate</b> </p> <p>The high level steps to query and set the bit and frame rate: </p> <ul><li id="GUID-AA205B92-155C-5E21-8DD7-A78E793F65DE"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-75E33792-E4AD-39BA-9129-15E731DD32D7"><apiname>CVideoPlayerUtility::VideoBitRateL()</apiname></xref>: This function returns the bit rate of the video clip. This returns the video clip's bit rate in bits per second. </p> <codeblock id="GUID-B5BFDD9A-B521-5A60-B278-57E72E9311DD" xml:space="preserve">TInt CPlayVideo::VideoBitRateL() 

    {

    return iVideoUtility->VideoBitRateL();

    }</codeblock> </li> <li id="GUID-254E33F2-3169-51E1-B964-3E8D0107D79C"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-BF2B4086-4682-3A37-AB02-859A02B0A3EF"><apiname>CVideoPlayerUtility::VideoFrameRateL()</apiname></xref>: This function returns the video frame rate. This returns the video frame rate in frames per second. </p> <codeblock id="GUID-FFFC156C-927A-564B-92B0-0E7D99ED506C" xml:space="preserve">TReal32 CPlayVideo::VideoFrameRateL()

    {

    return iVideoUtility->VideoFrameRateL();

    }</codeblock> </li> <li id="GUID-0136372C-744E-5C85-B3F8-8E4F6921B7A2"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-AC9ACAC4-44AD-3FC0-8E03-58DB0A641EE0"><apiname>CVideoPlayerUtility::SetVideoFrameRateL()</apiname></xref>: This function is used to set the number of video frames to be displayed per second. </p> <codeblock id="GUID-79D3C6D7-7E4F-5292-9221-6BCAEE88302B" xml:space="preserve">void CPlayVideo::SetVideoFrameRateL(TReal32 aFramesPerSecond)

    {

    iVideoUtility->SetVideoFrameRateL(aFramesPerSecond);

    }</codeblock> </li> </ul> <p> <b>Note:</b> The presence of an audio track within a video clip can be determined using <xref href="GUID-A230A2A3-FAFA-3F6F-A6C1-67B407779A87.dita"><apiname>AudioEnabledL()</apiname></xref>. </p> <p id="GUID-7D998004-DC09-5328-B2EE-AA363FB2D1C5"><b>Querying and Setting the Current Playback Position</b> </p> <p>The current playback position can be queried and set using the following functions: </p> <ul><li id="GUID-B3CC86FB-3169-5760-A289-7AAA7F5E6BF6"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-A000D8FD-DFA7-3402-A7AF-E8958E4AD252"><apiname>CVideoPlayerUtility::PositionL()</apiname></xref>: This function returns the current playback position. It returns the current position from the start of the clip in microseconds. </p> </li> <li id="GUID-3822C893-A609-5E8E-995B-C92D637CF435"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-F1E338F3-F683-3B21-9CAC-79A3B0996587"><apiname>CVideoPlayerUtility::SetPositionL()</apiname></xref>: This function sets the position for the playback within the video clip to start. </p> <codeblock id="GUID-704F61E0-A79A-56B5-8814-9F332681188C" xml:space="preserve">TTimeIntervalMicroSeconds pos;

TTimeIntervalMicroSeconds CPlayVideo::PositionL() \\ retrieves the current playback position within the video clip

    {

    return iVideoUtility->PositionL();

    } </codeblock> </li> </ul> <p id="GUID-0A67AED6-860A-5D84-9CE3-6E30A673DD82"><b>Querying and Setting the MIME and Codec Type</b> </p> <p>This section explains the functions that reports and sets the MIME type and codecs for video and audio data that is already open. The functions are as stated below: </p> <ul><li id="GUID-2A5F777D-1AFE-5798-A818-B4772185B741"><p> <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-58238242-AB6D-3A09-8212-1724244F69B0"><apiname>CVideoPlayerUtility::VideoFormatMimeType()</apiname></xref>: This returns the current MIME type of the video clip currently open. </p> <codeblock id="GUID-1CF87BE3-6249-55FB-8E37-2ACE38E73090" xml:space="preserve">const TDesC8 &amp; CPlayVideo::VideoFormatMimeType() 

    {

    return iVideoUtility->VideoFormatMimeType();

    }</codeblock> </li> <li id="GUID-8558289D-3599-57D7-8571-50A49012D433"><p>The datatype of the audio track used by the video clip can be retrieved using and <xref href="GUID-5298E3BF-4840-3FFD-B74D-D324B0386EDE.dita"><apiname>AudioTypeL()</apiname></xref>. </p> <codeblock id="GUID-789FF0CC-9115-5BA1-879E-FDFDA76F5EFE" xml:space="preserve">TFourCC CPlayVideo::AudioTypeL() \\retrieves the codecs used by audio track

    {

    return iVideoUtility->AudioTypeL();