Revision as of 09:00, 19 November 2011

UMMS User Manual and Sample code

Introduction

This page provides the User Manual and some sample code for the Universal Multi Media Service (UMMS).
UMMS general description can found on its main page

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

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 creat 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 creat 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.

  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 stream media.
    Parameters:
               is_stream(out): True for stream 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
  Eof
  Error(u: id, s: message)
  Buffering
  Buffered
  RequestWindow
  Seeked
  Stopped
  PlayerStateChanged(i: old_state, i: new_state)
  NeedReply
  TargetReady(a{sv}: info)
  Suspended
  Restored
  NoResource
  VideoTagChanged(i: video_number)
  AudioTagChanged(i: audio_number)
  TextTagChanged(i: text_number)

• Interface: com.UMMS.AudioManger'

Methods:

  SetVolume(i: output_type, i: volume)
  GetVolume(i: output_type, i(out): volume)
  SetState(i: output_type, i: state)
  GetState(i: output_type, i(out): state)

Sample Code