Latest revision as of 13:32, 5 February 2013

UMMS User Manual and Sample code

Introduction

This page is the user manual and some sample code for the Universal Multi Media Service (UMMS).
The UMMS general description is on the main page.

Source code

You can get the code from: git://gitorious.org/meego-middleware/umms.git

Mailing for question https://lists.tizen.org/listinfo/general

Service Name

com.UMMS

Objects and Interfaces

ObjectManager: Object to create and remove MediaPlayer object.

 Path:      /com/UMMS/ObjectManager
 Interface: com.UMMS.ObjectManager.iface

MediaPlayer: Player object to control the playback of media assets.

 Path:      Returned by ObjectManager
 Interface: com.UMMS.MediaPlayer

AudioManager: Object to manage the system audio output.

 Path:      /com/UMMS/AudioManager
 Interface: com.UMMS.AudioManger

VideoOutput: Object to control the display.

 Path:      /com/UMMS/VideoOutput
 Interface: com.UMMS.VideoOutput

PlayingContentMetadataViewer: Object to provide the metadata of all currently playing content.

 Path:      /com/UMMS/PlayingContentMetadataViewer
 Interface: com.UMMS.PlayingContentMetadataViewer

API Reference

• Interface com.UMMS.ObjectManager.iface

Methods:

  RequestMediaPlayer(s(out): object_path)
    Request a MediaPlayer object operate in attended-execution mode. The ObjectManager will create a new MediaPlayer object,
    register the object on the bus and return the object path to client.
    Parameters: 
        object_path(out): The object path belongs to the newly created MediaPlayer object.

  RequestMediaPlayerUnattended(d: time_to_execution, s(out): token, s(out): object_path)
    Request a MediaPlayer object operate in unattended-execution mode. The ObjectManager will create a new MediaPlayer object,
    register it on the bus and return the object path to client.
    Parameters:
               time_to_execution: Times in seconds for which this MediaPlayer object keep alive.
               token(out):        The unique token belongs to this execution. Application can use it to identify the execution log file which 
                                  named by the token. 
               object_path(out):  The object path belongs to the newly created MediaPlayer object.

  RequestScheduledRecorder(d: start_time, d: duration, s: uri, s: location, s(out): token, s(out): object_path)
    Request a MediaPlayer object operate in unattended-execution mode and schedule it to record the media pointed by "uri". The ObjectManager will create a 
    new MediaPlayer object, register it on the bus and return the object path to client.
    Parameters:
               start_time:        The delay to start recording in seconds.
               duration:          How long to record, in seconds.
               uri:               Specify the media to record.
               location:          Location to store the recorded media.
               token(out):        The unique token belongs to this execution. Application can use it to identify the execution log file which 
                                  named by the token. 
               object_path(out):  The object path belongs to the newly created MediaPlayer object.

  RemoveMediaPlayer(s: object_path)
    Remove the MediaPlayer object which was exposed on the object_path.
    Parameters:
               object_path: The path on which this object was exposed.
   

• Interface com.UMMS.MediaPlayer

Methods:

  SetUri(s: uri)
    Set URI to UMMS.
    Parameters:
               uri: URI to set.

  SetSubtitleUri(s: sub_uri)
    Set subtitle URI to UMMS.
    Parameters:
               sub_uri: URI to identify the subtitle file.

  GetCurrentUri(s(out): current_uri)
    Get current URI.
    Parameters:
               current_uri(out): current URI.

  SetTarget(i: type, a{sv}: param)
    Set video target and pass all target parameters to UMMS. The video target is where your decoded video data should be rendered.
    Parameters:
               type:  The type of video target.
                      0:XWindow,       the video data will be rendered on the X Window.
                      1:DataCopy,      the video data will be copied to a memory instead of directly rendering. E.g. copied to a GL Texture. 
                      2:Socket,        the video data will sent to a socket.
                      3:ReservedType0, reserved for custom target.
                      4:ReservedType1, reserved for custom target.
                      5:ReservedType2, reserved for custom target.
                      6:ReservedType3, reserved for custom target.
               param: The list of key-value pair to specify the attributes of the target. The definition of attribute structure is 
                      target-specific and up to the implementor. The UMMS framwork just defined the XWindow target attribute: 
                      Key          Value
                      "window-id"  value of "i" type indicates the window id. 

  Play()

  Pause()

  Stop()

  SetPosition(x: pos)
    Seek to position.
    Parameters:
               pos: Stream position in millisecond.

  GetPosition(x(out): pos)
    Get the current position of stream in millisecond.
    Parameters:
               pos(out): The current stream position.

  SetPlaybackRate(d: rate）
     Set the playback rate. 
    Parameters:
               rate: rate to playback the media asset.

  GetPlaybackRate(d(out): rate）
     Get current playback rate.
    Parameters:
               rate(out): The current playback rate.

  SetVolume(i: volume)

  GetVolume(i(out): volume)

  SetVideoSize(u: x, u: y, u: w, u: h)
    Set video dimension.
    Paramters:
              x: X coordinate of top-left.
              y: Y coordinate of top-left.
              w: Width of video rectangle.
              h: Height of video rectangle.

  GetVideoSize(u(out): w, u(out): h)
    Get current width and height of video rectangle.
    Parameters:
               w(out): Width of current video rectangle.
               h(out): Height of current video rectangle.

  GetBufferedTime(x(out): length_time)
    Get the approximate duration of playable data downloaded so far in millisecond.
    Parameters:
               length_time(out): amount of playable data downloaded so far in millisecond.

  GetBufferedBytes(x(out): length_byte)
    Get the approximate amount of playable data downloaded so far in bytes. 
    Parameters:
               length_byte(out): amount of playable data downloaded so far in byte.

  GetMediaSizeTime(x(out): duration)
    Get the duration of the media.
    Parameters: 
               duration(out): duration in millisecond.

  GetMediaSizeBytes(x(out): size)
    Get the total size of the media file.
    Parameters:
               size(out): total size of the media file.

  HasVideo(b(out): has_video)
    Indicates the existance of video stream in the media asset.
    Parameters:
               has_video(out): True if media asset has video. False otherwise.

  HasAudio(b(out): has_audio)
    Indicates the existance of audio stream in the media asset.
    Parameters:
               has_audio(out): True if media asset has audio. False otherwise. 

  IsStreaming(b(out): is_stream)
    Indicates whether the URI represents a streaming media.
    Parameters:
               is_stream(out): True for streamimg media. False otherwise.

  IsSeekable(b(out): is_seekable)
    Indicates whether this media asset is seekable.
    Parameters:
               is_seekable(out): True for seekable. False otherwise.

  SupportFullScreen(b(out): support_fullscreen)
    Indicates whether the backend supports a fullscreen mode.
    Parameters:
               support_fullscreen(out): True if backend supports fullscreen. False otherwise.

  GetPlayerState(i(out): current_state)
    Get current state of MediaPlayer object.
    Parameters:
               current_state(out): 
                                  0:Null,
                                  1:Stopped,
                                  2:Paused,
                                  3:Playing

  Reply()
    Response the UMMS server’s heartbeat check. In the attended-execution mode, client should connect to NeedReply
    signal with a callback in which Reply() method should be called.

  SetProxy(a{sv}: param)
    Set proxy stuffs.
    Parameters:
               param: A list of key-value pair to sepcify the proxy attributes.
                      The attribute structure is defined as:
                      Key          Value
                      "proxy-uri"  value of "s" type indicates HTTP proxy server URIl
                      "proxy-id"   value of "s" type indicates HTTP proxy user id for authentication.
                      "proxy-pw"   value of "s" type indicates HTTP proxy user password for authentication

  Suspend()
    Suspend current execution of player. After this invoking, all the resources ocuppied by this session will be released.

  Restore()
    Play the media asset from the position at where it suspended.

  GetCurrentVideo(i(out): current_video)
    Get current playing video stream.
    Parameters:
               current_video(out): stream number of current playing video.

  GetCurrentAudio(i(out): current_audio)
    Get current playing audio stream.
    Parameters:
               current_audio(out): stream number of current playing audio.

  GetCurrentSubtitle(i(out): current_sub)
    Get current playing subtitle stream.
    Parameters:
               current_sub(out): stream number of current playing subtitle.

  SetCurrentVideo(i: current_video)
    Choose the video stream to play.
    Parameters:
               current_video: stream number of video stream choosed to play.

  SetCurrentAudio(i: current_audio)
    Choose the audio stream to play.
    Parameters:
               current_audio: stream number of audio stream choosed to play.

  SetCurrentSubtitle(i: current_sub)
    Choose the subtitle stream to play. This method is for the media asset with embedded subtitle.
    Parameters:
               current_sub: stream number of subtitle stream choosed to play.

  GetVideoNum(i(out): video_num)
    Get total number of video streams.
    Parameters:
               video_num(out): Total number of video streams.

  GetAudioNum(i(out): audio_num)
    Get total number of audio streams.
    Parameters:
               audio_num(out): Total number of audio streams.
       
  SetBufferDepth(i: format, x: buf_depth)
    Set buffer depth when buffering network streams.
    Parameters:
               format: 0 for Time, 1 for Btye.
               buf_depth: The depth to buffer data. 

  GetBufferDepth(i: format, x(out): buf_depth)
    Get buffer depth.
    Parameters:
               format: 0 for Time, 1 for Btye.
               buf_depth(out): The depth to buffer data. 

  SetMute(i: is_mute)
    Mute the audio.
    Parameters:
               is_mute: 0 for unmute, 1 for mute.

  IsMute(i(out): is_mute)
     Get the mute state.
     Parameters:
                is_mute(out): 0 for unmute, 1 for mute.

  SetScaleMode(i: mode)
     Set the scale mode.
     Parameters:
                mode: 
                     0: do not scale.
                     1: fill entire target, regardless of original video aspect ratio.
                     2: scale the video with respect to original video aspect ratio.
                     3: fill the whole screen but keep the ratio, some part of video may out of screen.

  GetScaleMode(i(out): mode)
     Get the scale mode.
     Parameters:
                mode(out): 
                     0: do not scale.
                     1: fill entire target, regardless of original video aspect ratio.
                     2: scale the video with respect to original video aspect ratio.
                     3: fill the whole screen but keep the ratio, some part of video may out of screen.

  GetVideoCodec(i: num, s(out): video_codec)
     Get the codec of video stream specified by the "num".
     Parameters:
                num: video stream number.
                video_codec(out): codec string.

  GetAudioCodec(i: num, s(out): audio_codec)
     Get the codec of audio stream specified by the "num".
     Parameters:
                num: audio stream number.
                audio_codec(out): codec string.

  GetVideoBitrate(i: num, i(out): video_bitrate)
    Get the bitrate of video stream specified by the "num".
    Parameters:
                num: video stream number.
                video_bitrate(out): bitrate of the video stream.

  GetAudioBitrate(i: channel, i(out): audio_bitrate)
    Get the bitrate of audio stream specified by the "num".
    Parameters:
                num: audio stream number.
                audio_bitrate(out): bitrate of the audio stream.

  GetEncapsulation(s(out): encapsulation)
    Get the container format.
    Parameters:
               encapsulation(out): the container format.

  GetAudioSampleRate(i: num, i(out): sample_rate)
    Get the sample rate of audio stream specified by the "num".
    Parameters:
               num:              audio stream number.
               sample_rate(out): sample rate of the audio stream.

  GetVideoFrameRate(i: num, i(out): frame_rate_num, i(out): frame_rate_denum)
    Get the frame rate of video stream specified by the "num".
    Parameters:
               num:                   video stream number.
               frame_rate_num(out):   numerator of frame rate.
               frame_rate_denum(out): denumerator of frame rate.

  GetVideoResolution(i: num, i(out): width, i(out): height)
    Get the original resolution of the video stream specified by the "num".
    Parameters:
               num:         video stream number.
               width(out):  width of video.
               height(out): height of video.

  GetVideoAspectRatio(i: num, i(out): ratio_num, i(out): ratio_denum)
    Get the original aspect ratio of the video stream specified by the "num".      
    Parameters:
               num:              video stream number.
               ratio_num(out):   numerator of the aspect ratio.
               ratio_denum(out): denumerator of the aspect ratio.

  GetProtocolName(s(out): protocol_name)
    Get the tranport protocol name.
    Parameters:
               protocol_name(out): name of the protocol.

  Record(b: to_record, s: location)
    Start or stop the recording of current playing DVB stream.
    Parameters:
               to_record: True to start recording, False to stop recording.
               location:  path to store the record file.

  GetPat(aa{sv}(out): pat)
    Get the "Program Association Table".
    Parameters:
               pat(out): the "Program Association Table". 
                         The structure of pat is a list of mapping table. Each mapping table has two key-value pairs:
                         Key               Value
                         "program-number"  value of "u" type which indicates the program number. 
                         "pid":            value of "u" type which indicates the pid of the pat.

  GetPmt(u(out): program_number, u(out): pcr_pid, aa{sv}(out): stream_info)
    Get the "Program Map Table" of current playing DVB program.
    Parameters:
               program_number(out): the number of current playing program.
               pcr_pid(out):        the pcr pid.
               stream_info(out):    the information of all elementary streams multiplexed in this program.
                                    The structure of stream_info is a list of mapping table. Each mapping table has two key-value pairs:
                                    Key            Value
                                    "stream-type"  value of "u" type indicates the stream type.
                                    "pid"          value of "u" type indicates the pid of the elementary stream.

  GetAssociatedDataChannel(s(out): ip, i(out): port)
    Get the ip and port from which the client can retrive DVB associated data(ts packets).
    Parameters:
               ip(out):   ip string
               port(out): port string

Signals:

  Initialized
    Pipeline engine initialized.

  Eof
    End of file or stream.

  Error(u: id, s: message)
    Error happened.
    Parameters:
               id:      error id.
               message: error message.

  Buffering(i: percent)
    Buffering percent, from 0 to 100.

  Seeked
   Seeking done.

  Stopped
   Player stopped.

  PlayerStateChanged(i: old_state, i: new_state)
   Player state changed.
   Parameters:
              old_state: previous state of player, value definition is the same as state parameter of GetPlayerState. 
              new_state: current state of player, value definition is the same as state parameter of GetPlayerState.

  NeedReply
   Singal to request the client to reply. This is used for client existence checking. The client should call the Reply() method to response this 
   signal.

  Suspended
   The player has been suspended. That means all the resources ocuppied by this player has been released.

  Restored
   The player restored from suspened.

  NoResource
   Resource unavailable.

  VideoTagChanged(i: video_number)
   The metadata of a video stream changed.
   Parameters:
              video_number: video stream number.

  AudioTagChanged(i: audio_number)
   The metadata of a audio stream changed.
   Parameters:
              audio_number: audio stream number.

  TextTagChanged(i: text_number)
   The metadata of a text stream changed.
   Parameters:
              text_number: text stream number.

  RecordStart
   The recording started.

  RecordStop
   The recording stopped.

• Interface: com.UMMS.AudioManger

Methods:

  SetVolume(i: output_type, i: volume)
    Set the global audio volume on audio output specified by "output_type".
    Parameters:
               output_type: output type id.
                            0, hdmi
                            1, spidf
                            2, i2s0
                            3, i2s1
               volume:      volume to set, range [0, 100]

  GetVolume(i: output_type, i(out): volume)
    Set the global audio volume on audio output specified by "output_type".
    Parameters:
               output_type: output type id.
               volume(out): current volume.

  SetState(i: output_type, i: state)
    Mute/Unmute the audio output.
    Parameters:
                output_type: output type id.
                state:       0 to unmute, 1 to mute.

  GetState(i: output_type, i(out): state)
    Get the mute state of audio output.
    Parameters:
                output_type: output type id.
                state(out):  0 for unmute, 1 for mute.

• Interface: com.UMMS.VideoOutput

Methods:

  GetValidVideoOutput(as(out): outputs)
    Get name of all the outputs.
    Parameters:
               outputs(out): output names.

  GetValidMode(s:output_name, as(out): modes)
    Get valid display modes of a output specified by output_name
    Parameters:
               output_name：output name.
               modes(out):  valid display modes.

  SetMode(s:output_name, s: mode)
    Set display mode of the output.
    Parameters:
               output_name：output name.
               mode:       mode to set.

  GetMode(s:output_name, s(out): mode)
    Get current display mode of the output.
    Parameters:
               output_name：output name.
               mode(out):   current display mode.

• Interface: com.UMMS.PlayingContentMetadataViewer

Methods:

  GetPlayingContentMetadata(aa{sv}(out): playing_content_metadata)
    Get the current playing content metadata.
    Parameters:
               playing_content_metadata(out): media content metadata
                                             The structure of playing_content_metadata is a list of mapping table. Each mapping table has 3 key-value pairs:
                                             Key                 Value
                                             "URI"               Value of "s" type indicates the current playing URI.
                                             "Title"             Value of "s" type indicates the title of the playing media content
                                             "Artist"            Value of "s" type indicates the artist of the playing media content

Signals:

  MetadataUpdated(aa{sv}: metadata)
    Emitted when a metadata changed. e.g. A new player is requested to play a video.
    Parameters:
               metadata: The same as playing_content_metadata

Sample Code

This is a sample application written in Python to play a URI by requesting an attended-execution media player instance. You can get the latest code from: git://gitorious.org:meego-middleware/umms.git

import dbus
import dbus.mainloop.glib
import dbus.glib

player_iface = None
loop = None

def need_reply_cb ():
    player_iface.Reply()

def eof_cb ():
  print "EOF...."
  loop.quit()

#event loop
dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)

#get the system message deamon
bus=dbus.SystemBus()

#get the 'com.UMMS.ObjectManager.iface'
bus_obj=bus.get_object('com.UMMS', '/com/UMMS/ObjectManager')
obj_mngr=dbus.Interface(bus_obj, 'com.UMMS.ObjectManager.iface')

#request a media player for attended-execution
player_obj_path = obj_mngr.RequestMediaPlayer()
player_obj = bus.get_object("com.UMMS", player_obj_path)
player_iface =  dbus.Interface(player_obj, 'com.UMMS.MediaPlayer')

#for the attended-execution, we must connect to the "NeedReply" signal
player_iface.connect_to_signal("NeedReply", need_reply_cb)

#connect other signals you want
player_iface.connect_to_signal("Eof", eof_cb)

#play a URI
player_iface.SetUri("/tmp/sample.mp4")
player_iface.Play()

#event loop 
loop = gobject.MainLoop()
loop.run()