﻿/*
 * Copyright (c) 2011-2014, NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property
 * and proprietary rights in and to this software, related documentation
 * and any modifications thereto.  Any use, reproduction, disclosure or
 * distribution of this software and related documentation without an express
 * license agreement from NVIDIA Corporation is strictly prohibited.
 *
 * version: 0.2
 * <Cotigao>
 */

NvGstPlayer Usage
-----------------------------------------------
Run the nvgstplayer application with the following basic syntax:

./nvgstaplayer -i <uri>

nvgstplayer application support following options:

  -u, --urifile                     Path of the file containing the URIs
  -i, --uri                         input URI
  -r, --gst_script                  Path of the file containing the Script to be used
  --automotive                      Enter the AutoMotive Mode, to support GstMediaPlayer functionalities in NvGstPlayer
  -e, --elemfile                    Element(s) (Properties) file
  -x, --cxpr                        Command sequence expression
  -n, --loop                        Number of times to play the media
  -c, --audio-track                 If stream have multiple audio tracks, play stream with given track no
  -v, --video-track                 If stream have multiple video tracks, play stream with given track no
  -a, --start                       Start of the segment in media in seconds
  -d, --duration                    Play duration of the segment in media in seconds
  --no-sync                         Disable AV Sync
  --disable-dpms                    Unconditionally Disable DPMS/ScreenBlanking during operation and re-enable upon exit
  --stealth                         Operate in stealth mode, alive even when no media is playing
  --use-playbin                     Use Playbin
  --no-audio                        Disable audio
  --no-video                        Disable video
  --disable-anative                 Disable native audio rendering
  --disable-vnative                 Disable native video rendering
  --use-buffering                   Use Buffering
  -l, --low-percent                 Low threshold for buffering to start, in %
  -j, --high-percent                High threshold for buffering to finish, in %
  --loop-forever                    Play the URI(s) in loop forever
  -t, --max-size-time               Max. amount of time in the queue (0=automatic)
  -y, --max-size-bytes              Max. amount of bytes in the queue (0=automatic)
  -b, --max-size-buffers            Max. amount of buffers in the queue (0=automatic)
  --disable-fullscreen              Play video in non fullscreen mode (for nvxvimagesink)
  -h, --drop-threshold-pct          Permittable frames drop percentage, to be used with --stats (only for development purpose)
  -k, --image-display-time          Image display time in seconds
  --show-tags                       shows tags (metadata), if available
  --smartdimmer                     Enable smart dimmer for power saving
  --stats                           shows stream statistics, if enabled
  --stats-file                      File to dump stream statistics, if enabled
  --svd                             (=) chain for video decoding
  --sad                             (=) chain for audio decoding
  --svc                             (=) chain for video postprocessing
  --sac                             (=) chain for audio postprocessing
  --svs                             (=) chain for video rendering
  --sas                             (=) chain for audio rendering
  --shttp                           (=) chain for http source
  --srtsp                           (=) chain for rtsp source
  --sudp                            (=) chain for udp source
  --sfsrc                           (=) chain for file source

Runtime Commands:
   q                                quit the application
   h                                print help
   Up Key, ]                        goto next track
   c                                restart current track
   Down Key, [                      goto previous track
   spos                             query for position
   sdur                             query for duration
   s<val>                           seek to <val> position in seconds, eg "s5.120"
   v<val>                           seek to <val> percent of the duration, eg "v54"
   f<val>                           seek by <val> seconds, relative to current position eg "f23.901"
   Left Key, <                      seek backwards by 10 seconds
   Right Key, >                     seek forward by 10 seconds
   p                                pause playback
   r                                start/resume the playback
   z                                stop the playback
   x:<val>                          set overlay X coordinate eg "x:100"
   y:<val>                          set overlay Y coordinate eg "y:200"
   s:<valxval>                      set overlay size(wxh) eg "s:640x480"
   i:<val>                          enter a single URI

The nvgstplayer application supports local file playback, and playback from RTSP, HTTP and UDP streams.

For example:

./nvgstplayer -i /home/test.mp4
./nvgstplayer -i file:///home/test.mp4
./nvgstplayer -i udp://192.168.2.5:123

The nvgstplayer application operates in two modes, Playbin2 (--use-playbin) and Decodebin2. Decodebin2
allows you to choose elements.

A subset of options is documented below. For a complete description of available options use the --help option.


Audio/Video Decoder Chain (--sad/--svd)
---------------------------------------
Specify a desired decode chain for a particular URI using --sad or --svd, with the -i option or using a URI file with the -u option.

For example:

  --sad=”ffdec_mp3”
  --sad=”amrdec# variant=1 ! audioresample ! audioconvert”
  --sad=”aacparse ! faad# min-latency=4000000”
  --svd=”ffdec_h264# prop=val# prop2=val2”

Note the ‘#’  and  ‘!’  character after every token.


Audio/Video PostProcess Chain (--sac/--svc)
------------------------------------------
Specify a desired postprocess chain for a particular URI using --sac or --svc, with the -i option or using a URI file with the -u option.

For example:

  --sac=”audioconvert ! audioresample”
  --svc= “my_video_postprocess# prop1=val1 ! ffmpegcolorspace ! videoscale”

Note the ‘#’  and  ‘!’  character after every token. To include this in your pipeline
use the -–disable-anative/--disable-vnative options, or, in a URI a file,
native_video=0/native_audio=0.

Audio/Video Render Chain (--sas/--svs)
--------------------------------------
Specify a desired render chain for a particular URI using --sas or --svs with the -i option or using a URI file with the -u option.

For example:

  --sas=”alsasink# device=hw:0,0”
  --sas=”audioconvert ! alsasink”
  --svs= “xvimagesink”
  --svs = “ffmpegcolorspace ! videoscale ! ximagesink# sync=0”

Note the ‘#’  and  ‘!’  character after every token.


Elements file (--elemfile/-e)
-----------------------------
Specfy with --elemfile (or -e) an input file containing the sources, decoders, parsers, postprocess, and sinks that you want to use.


Decoders/Parsers Chain Format
-----------------------------
[capabilties]
type=<val>, val = ‘sad’, ‘svd’
pipe=<my_chain>


Post Process/Render chain Format
-------------------------------
[type]
pipe=<my_chain>

For example:

[video/x-h264]
type=svd
pipe=h264parse ! my_h264_dec# prop1=val1

[svs]
pipe=xvimagesink

[sas]
pipe=audioconvert ! osssink# device=/dev/dsp1# latency-time=20000#

[video/mpeg, mpegversion=4]
type=svd
pipe= ffdec_mpeg4

[audio/mpeg, mpegversion=1, layer=3]
type=sad
pipe= mp3parse ! mad

[audio/mpeg, mpegversion=4]
type=sad
pipe=faad

[svc]
pipe= ffmpegcolorspace# qos=0 ! videoscale


Command Sequence Expression (--cxpr/-x)
---------------------------------------
Use the --cxpr (or -x) option (as a string) to provide a series of commands in an expression format.
The following commands can be inserted in an expression:

r<val>    play for <val> seconds until next command in the expression
p<val>    pause for <val> seconds until next command in the expression
z<val>    stop for <val> seconds until next command in the expression
w<val>    do nothing for <val> seconds until next command in the expression
s<val>    seek to absolute time <val> seconds
v<val>    seek to absolute time <val> in % of duration
f<val>    seek to relative time <val> seconds from current position
>         seek forward by 10 seconds
<         seek behind by 10 seconds
]         goto next track
[         goto previous track
c         reset current track

For example:

r10.5,s80,w5,p7,r
2{p10,r,w7,s90.55,w2,p,w10,r2} <will iterate the expression 2 times>
2{r20,s10,w5,p10, 2{s10,w6,r9}, 3{r10, p20}}
5{r8, p10, s90, w10}, 8{s10, w2, p20}

Random cxpr:
------------
A random command sequence expression can be generated by giving cxpr as "*"

For example:

./nvgstplayer -i <uri> --cxpr=*

This will generate a random command sequence expression (up to 100 characters).


URI File (--urifile/-u)
-----------------------
Use the --urifile (or -u) option to specify a list of URIs. The player plays all URIs listed in the file. Any options for the URI specified in the file take precedence over the same options set by application command line arguments for that particular URI.

Format of the URI file and the options for the URI
------------------------------------------------
[uri1]
option1=val1
option2=val2
.......
........

[uri2]
option1=val1
..........
..........

List of all possible options for URIs inside URI file
-----------------------------------------------------
cxpr=<val>                       command expression for the URI
nop=<val>                        if  '1' , will disable the global cxpr (if given as command line arg)
start=<val>                      start playback time in seconds/ or percentage of URI duration
startper=<val>                   '1' indicating that the 'start' option will be % value
duration=<val>                   desired playback time in seconds
repeats=<val>                    playback iterations
audio=<val>                      0/1 to disable/enable audio in the URI
video=<val>                      0/1 to disable/enable video in the URI
native_video=<val>               0/1 to disable/enable native video rendering
native_audio=<val>               0/1 to disable/enable native audio rendering
sync=<val>                       1/0 to enabling/disabling AV sync
use-buffering=<val>              1/0 to enable/disable buffering
low-percent=<val>                low threshold for buffering in %
high-percent=<val>               high threshold for buffering in %
max-size-bytes=<val>             max size of bytes in queue for buffering
max-size-buffers=<val>           max size of buffers in queue for buffering
max-size-time=<val>              max size time in queue  for buffering
image-display-time=<val>         image display time in seconds (if URI is an image file)
tags=<val>                       0/1 disable/enable tags print
svd=<val>                        video decoding chain
sad=<val>                        audio decoding chain
svc=<val>                        video post-precessing chain
sac=<val>                        audio post-precessing chain
svs=<val>                        video rendering chain
sas=<val>                        audio rendering chain
shttp=<val>                      http source chain
srtsp=<val>                      rtsp source chain
sudp=<val>                       udp source chain
sfsrc=<val>                      file source chain


For example, use the following as a URI file with the syntax "./nvgstplayer -u TestURIfile":

TestURIfile

[/home/user/test.avi]
cxpr=2{p5, r, w10, s20.5, w6.6, p3, 2 {r, w10, p4}}
start=10.45
repeats=3
audio=0
native_video=0
svd=my_h264dec
svc=ffmpegcolorspace ! my_pp# prop1=shuba# prop2=val2# ! videoscale

[/home/user/test.mp3]
sas=audioconvert ! alsasink

[/home/user/test.mp4]
nop=1
video=0


NOTES:

1. Elements to use can be provided in several different ways:

   a. Provided in an elements file.

   b. Provided as command-line arguments applicable to all the streams in the URI file, with the –I option. Elements provided in this way override values (if present) inside an elements file.

   c. Provided in a URI file, specific for each URI, if desired. Elements provided in this way override any elements provided at the command-line or in an elements file.

2. Use following amixer settings (for K3.1) to enable audio playback through the device's internal speaker:

  amixer cset name='Speaker Switch' on
  amixer cset name='Speaker ZC Switch' on
  amixer cset name='Line Out ZC Switch' on
  amixer cset name='Right Speaker Mixer DACL Switch' on
  amixer cset name='Right Speaker Mixer DACR Switch' on
  amixer cset name='Right Speaker Mixer Left Bypass Switch' on
  amixer cset name='Right Speaker Mixer Right Bypass Switch' on
  amixer cset name='Left Speaker Mixer DACL Switch' on
  amixer cset name='Left Speaker Mixer DACR Switch' on
  amixer cset name='Left Output Mixer Left Bypass Switch' on
  amixer cset name='Left Output Mixer Right Bypass Switch' on
  amixer cset name='Digital Playback Volume' 120,120
  amixer cset name='Speaker Volume' 63,63


3. The uri list can be looped forever by providing --loop-forver option:

  ./nvgstplayer -u <uri_file> --loop-forever
