1enplayer(1)                                                        enplayer(1)
2
3
4

NAME

6       enplayer - GStreamer media/pipeline player
7

SYNOPSIS

9       enplayer [OPTION]... {--} {MEDIA}...
10

DESCRIPTION

12       enplayer  is  a  GStreamer  based  media player implemented as a python
13       script. While it may or may not be unique in that,  it  has  been  made
14       with the following goals in mind;
15
16       • plain-and-simple,  e.g.  no  GUI  trimmings, other than (of course) a
17         video window also offering a minimal OSD (whenever possible). On  the
18         other  hand, a small codebase that runs simply as a standalone script
19         and needs no special installation, other than having the sibling  en‐
20         trans script alongside for some shared support code.
21
22       • to serve as a key-binding layer that maps some input key to GStreamer
23         API in a flexible and configurable way. In that regard, it aims to be
24         a python based interactive gst-launch(1) (with controllable key-bind‐
25         ing mapping keystrokes to commands that allow e.g. setting any  pipe‐
26         line element property at runtime).
27
28       • to  suit  both  regular desktop use as well as a developer diagnostic
29         tool, e.g.  runnable on an embedded target controlled over  ssh  com‐
30         mand line (and, in fact, it evolved from such a tool/script). In par‐
31         ticular, it has only a limited set of python module dependencies, and
32         will  enable  features and capabilities depending on (runtime) avail‐
33         able python bindings/modules (and their  native  library  implementa‐
34         tions).  Moreover,  it  does  not  favour  or  expect  any particular
35         videosink,  though  some  features   require   proper   support   for
36         GstVideoOverlay (as is typically the case anyway).
37
38       • to support playbin based dynamic pipelines, but to degrade gracefully
39         and still provide as much features as possible for  custom  specified
40         pipelines (in advanced developer use cases)
41
42       At  a  minimum,  it requires a GStreamer installation with a convenient
43       set of plugins along  with  gobject-introspection  data  for  GStreamer
44       core.   The  media types supported by enplayer are determined solely by
45       the set of plugins, and both the default set and additional availabili‐
46       ty likely depend on the particular distribution.
47

USAGE

49       For simple media playing, it accepts a list of media URIs and will play
50       each in turn, where a simple file path is also accepted (and  converted
51       into a file:// URI).  Again, the set of supported URIs is determined by
52       the GStreamer  installation,  but  likely  includes  http://,  rtsp://,
53       dvd://. A much more impressive listing could be provided here, but e.g.
54       gst-inspect(1)'s -u option will show what is available.
55
56       Without further delay, the default key  bindings  during  playback  are
57       then as follows:
58
59       ## Enplayer input control file
60       ##
61       ## Key bindings can be added or redefined here
62       ## Functions are documented along with arguments
63       ## (use ignore as function to unbind a key)
64       ##
65       ## Bindings are added to default binding table from following files:
66       ##   ~/.config/enplayer/input.conf
67       ##
68
69       # (int seconds)
70       # relative seek
71       d seek 10
72       D seek 60
73       b seek -10
74       B seek -60
75       g seek 300
76       G seek 600
77       n seek -300
78       N seek -600
79       RIGHT seek 10
80       LEFT seek -10
81       UP seek 60
82       DOWN seek -60
83       PGUP seek 600
84       PGDOWN seek -600
85
86       # (un)pause
87       p pause
88       SPACE pause
89
90       # (int volinc)
91       # adjust volume
92       / volume -1
93       9 volume -1
94       * volume 1
95       0 volume 1
96
97       # (un)mute
98       m mute
99
100       # cycle OSD mode
101       o osd
102
103       # (int inc)
104       # switch video stream
105       _ switch_video 1
106
107       # (int inc)
108       # switch audio stream
109       # switch_audio 1
110
111       # (int inc)
112       # switch subtitle stream
113       J switch_sub -1
114       j switch_sub 1
115
116       # toggle subtitle visibility
117       v sub_visibility
118
119       # cycle through aspect-ratios
120       a switch_aspect_ratio
121
122       # (float rate)
123       # scale playback speed
124       [ speed_mult 0.9091
125       ] speed_mult 1.1
126       { speed_mult 0.5
127       } speed_mult 2.0
128       x speed_mult -1.0
129
130       # (float rate)
131       # set playback speed
132       BS speed_set 1.0
133
134       # (int offset_adjust_ms)
135       # adjust audio delay
136       + audio_delay 100
137       - audio_delay -100
138
139       # toggle repeat play of each playlist item
140       r repeat
141
142       # toggle looping of playlist
143       l loop
144
145       # toggle keyframe seeking
146       k keyframe
147
148       # toggle window fullscreen; only supported by toolkit backend
149       f fullscreen
150
151       # (int displaysize)
152       # take a .png screenshot with raw video size or displayed size
153       s screenshot 0
154       S screenshot 1
155
156       # (int steps)
157       # frame step
158       . frame_step 1
159       6 frame_step 1
160       4 frame_step -1
161
162       # (int direction)
163       # keyframe step (positive next, negative previous)
164       8 keyframe_step 1
165       2 keyframe_step -1
166
167       # (int inc, int overboundary=0)
168       # skip to previous/next entry in playlist possibly going over the begin/end
169       < pt_step -1
170       > pt_step 1
171       ENTER pt_step 1 1
172
173       # show help (man page)
174       F1 help
175
176       # (str elregexp, str prop, str value)
177       # find an element el by matching elregexp against its name, path string,
178       # factory name, any supertype or any implemented interface and
179       # set property prop of el to value
180       CTRL-2 prop_set fillel fillprop
181
182       # (str elregexp, str prop, float term)
183       # find an element el by matching elregexp against its name, path string,
184       # factory name, any supertype or any implemented interface and
185       # add term to property prop of el
186       CTRL-3 prop_add fillel fillprop 0
187
188       # (str elregexp, str prop, float factor)
189       # find an element el by matching elregexp against its name, path string,
190       # factory name, any supertype or any implemented interface and
191       # mult property prop of el with factor
192       ALT-4 prop_mult fillel fillprop 1.0
193
194       # (str elregexp, str prop)
195       # find an element el by matching elregexp against its name, path string,
196       # factory name, any supertype or any implemented interface and
197       # toggle property prop of el
198       ALT-5 prop_toggle fillel fillprop
199
200       # quit
201       q quit
202       ESC quit
203
204
205       One might notice that these default bindings closely match those of en‐
206       player's phonetic precursor.  The key bindings can easily be tweaked to
207       taste  by  placing  definitions such as the above in e.g. ~/.config/en‐
208       player/input.conf.
209
210       If some desired function/command seems missing  from  the  above  list,
211       then  also  have a look at EXAMPLES where some common functions are im‐
212       plemented using generic commands.
213
214       If enplayer is started from terminal (command line), then at the  start
215       of  playing  each clip some information is displayed including the dis‐
216       covered streams along with tag metadata.  In addition, status lines up‐
217       dated during playback provide following information:
218
219       • video frame and display size, as well as display aspect-ratio
220
221       • audio-video offset (as set by audio_delay command in the above list)
222
223       • playback (segment) rate
224
225       • current  position  (as  determined by GST_QUERY_POSITION).  In paused
226         state, however, position is given by last video sample's stream time.
227         Also,  a  +  prefix  is  added if the latter is non-trivial, i.e. not
228         equal to the sample buffer's PTS, and a frame number is shown as well
229         (simply derived linearly based on discovered framerate).
230
231       • clip duration (as determined by GST_QUERY_POSITION)
232
233       • clip position in percentage (ratio of foregoing items)
234
235       • current video, audio and subtitle stream (where applicable)
236
237       • current audio volume (on cubic or linear scale)
238
239       • a  number  of  status flags displayed in bold if enabled and prefixed
240         with ! if disabled;
241
242         S      whether clip is seekable (GST_QUERY_SEEKING),
243
244         K      whether keyframe seeking is active,
245
246         R      whether repeat play is active,
247
248         L      whether loop play is active,
249
250       When playing a media URI, the pipeline is playbin based.   However,  as
251       alluded to above, a custom pipeline can also be specified while retain‐
252       ing as much player functionality as  possible,  e.g.  (un)pause,  seek,
253       step  operations and providing information on caps, tags, duration, po‐
254       sition etc (though obviously, there are no evident/defined  streams  to
255       switch between for example).
256

OPTIONS

258       As  will be noticed, some options are shared with and influenced by the
259       quintessential diagnostic tool gst-launch(1) or enplayer's sibling  en‐
260       trans,  although  quite  some  others  are more specific to the setting
261       here.  In any case, enplayer accepts the options presented in the  fol‐
262       lowing  sections, most of which have shortname (one-letter) or longname
263       forms.  The ordering of the options is not strict, and options  can  be
264       single-valued or multi-valued.
265
266       • In  the  former case, which is the default unless otherwise indicated
267         below, only the value given last is retained.   In  particular,  this
268         includes boolean options.
269
270       • Otherwise,  for multi-valued options, all values given are taken into
271         consideration.  In these cases, it may sometimes also be possible  to
272         pass several values per single option occurrence, by comma-separating
273         these values as indicated in each such case below. This will typical‐
274         ly  be  the  case  in those instances where there can be no ambiguity
275         since the supplied value does not include free-text.
276
277       -h, --help
278         Show a brief help message.
279
280   BASIC OPTIONS
281       Most of the following options apply whether or not the pipeline is cus‐
282       tom.   However,  in  either  case, some depend on enplayer successfully
283       finding the element serving as video sink (as it automagically tries to
284       do) or providing GstStreamVolume interface.
285
286       --no-audio, --no-video, --no-sub, --no-video
287              [non-custom  only]  Disable  rendering  of  the specified stream
288              type.
289
290              As an implementation note, this simply masks  the  corresponding
291              playbin flags (after any custom flag setting has been applied).
292
293       --aspect-ratio W:H
294              enplayer  holds  a list of standard (display) aspect-ratios that
295              can be cycled through (media-specified, 4:3 or 16:9).  This  op‐
296              tions  adds the specified ratio to the list and makes it the ac‐
297              tive entry (thereby forcing the specified display aspect-ratio).
298
299       --screenshot-file file
300              Filename to save (png) screenshot to when requested, subject  to
301              having  [PTS]  replaced  by  the frame's (buffer) (presentation)
302              timestamp.
303
304       --linear
305              Volume (percentage or slider) is usually displayed  on  a  cubic
306              scale  (as  customary in the PulseAudio framework).  This option
307              will use a linear scale instead (as might be found in ALSA slid‐
308              er display).  See also example ALSA volume control.
309
310       --dvd-device device
311              Specifies the dvd device or file.
312
313              Technically,   this   is   merely  a  convenient  shorthand  for
314              --set-prop   dvdreadsrc:dvd-device:device   --set-prop   rsndvd‐
315              bin:dvd-device:device
316
317       --geometry WIDTHxHEIGHT+XOFF+YOFF
318              A  standard  XWindows geometry specification, see e.g.  X(1) for
319              details.
320
321       --disable-screensaver method
322              Specify the method to disable screensaver (and  suspend)  during
323              playback.  Possible choices for method are:
324
325              none   No screensaver disabling
326
327              dbus   Use a (heuristically determined) DBus interface
328
329              xdg    Use xdg-screensaver
330
331              auto   Try the dbus way and fallback to xdg
332
333       --osd method
334              [non-custom only] As enplayer is sink-agnostic, a minimal OSD is
335              implemented by composing some standard elements into a bin  that
336              is  used  as  video filter on playbin (inserted after a user-set
337              video filter, if any).  Possible choices for method are:
338
339              none   Ensures a pristine pipeline with no OSD whatsoever
340
341              ascii  OSD using only ASCII text
342
343              standard
344                     OSD using Unicode character set text
345
346              graphic
347                     OSD as with standard, but also using a graphic slider
348
349       --set-prop element:prop:value
350              Sets property prop of element to value, where element can either
351              be a factory name, or the name or full path-string of a specific
352              element.  Note that a value given for a property within a  (cus‐
353              tom)  pipeline description will override any value provided this
354              way. More precisely, this option will not set a property  if  it
355              is already set to a non-default value.
356
357              The  rank  of an element (as a plugin feature), which (a.o.) de‐
358              termines whether/how it is used for  auto-plugging  (by  playbin
359              and  friends) is considered as a pseudo-property pf_rank and can
360              therefore be set in this way as well to influence dynamic  pipe‐
361              line construction.
362
363   ADVANCED OPTIONS
364       Many  of  the  following options are of gst-launch(1) descent and apply
365       both to a custom or a dynamically constructed player pipeline.
366
367       --no-toolkit
368              enplayer normally tries to setup a window of its  own  and  then
369              uses  GstVideoOverlay  interface  to  pass  this along suitably.
370              This option disables such setup, so video window  management  is
371              entirely  up  to a video sink (as in gst-launch(1) case).  Since
372              the latter is then not enplayer's business, it follows there  is
373              no  window geometry management (e.g. no fullscreen) and that key
374              events are not received from the video window  (navigation  mes‐
375              sages are then used instead, typically with little or no modifi‐
376              er key consideration).
377
378       In the following, proppattern is a  regular  expression  that  will  be
379       matched against a combination of an element and (optionally) one of its
380       properties prop. More precisely, this combination matches if the  regu‐
381       lar expression matches any of the following:
382
383element's factory name.prop
384
385element's name.prop
386
387element's path name.prop
388
389       In  each case, the last part is omitted if there is no prop in the con‐
390       text in question.
391
392       Similarly, msgpattern is matched against expressions as above, but with
393       prop  replaced  by message type name.message structure name.  Again, in
394       each case, the last part is omitted if there is no  structure  for  the
395       message in question.
396
397       -m     Output messages posted on the pipeline's bus
398
399       --ignore-msg msgpattern[,...] , --display-msg msgpattern[,...]
400              [multi-valued]  If  message reporting is enabled by -m, only re‐
401              port on those that match --display-msg or  do  not  match  --ig‐
402              nore-msg
403
404       -v     Provide  output  on property changes of the pipeline's elements.
405              This output can be filtered using -x
406
407       -x proppattern[,...] , --exclude proppattern[,...] , --include proppat‐
408       tern[,...]
409              [multi-valued]  If  property  change reporting is enabled by -v,
410              only report those on properties that match --include or  do  not
411              match --exclude
412
413       -p, --prop
414              Also report a summary of properties that have been notify'ed (to
415              a non-default value) during start-up of media playback
416
417       --display-prop proppattern[,...] , --ignore-prop proppattern[,...]
418              [multi-valued] An element's  property  (value)  is  reported  at
419              start-up if and only if it matches an expression given in --dis‐
420              play-prop or its value differs from the  default  value  and  it
421              does not match --ignore-prop.
422
423       --raw  Switches  into  custom  pipeline mode, where all remaining argu‐
424              ments are collected and whitespace-joined into  a  pipeline  de‐
425              scription (in the usual gst-launch(1) way).
426
427   CONFIGURATION OPTIONS
428       Each enplayer option —be it one affecting enplayer's run-time behaviour
429       or affecting pipeline element (properties)— can also be provided  on  a
430       more  permanent basis using a configuration file.  Such a file consists
431       of sections, led by a [section] header and followed by name: value  en‐
432       tries,  name=value  is  also accepted.  Note that leading whitespace is
433       removed from values.  Lines beginning with # or ; are ignored  and  may
434       be used to provide comments.
435
436       In  the special section [options], each entry name: value is equivalent
437       to providing --name value on the command-line, where name  must  be  an
438       option's longname.  If the option is multi-valued and does not accept a
439       comma-separated list of values, then name may also have _0 or  _1  (and
440       so forth) appended to it.  The name of any other section is interpreted
441       as an element, with each entry providing a value for a property.   Oth‐
442       erwise  put,  each  prop: value in a section [element] is equivalent to
443       mentioning it in --set-prop as element:prop:value
444
445       Any setting provided on the command line  for  a  single-valued  option
446       (e.g. a boolean option) overrides a similar value given in a configura‐
447       tion file, whereas values provided  for  multi-valued  ones  append  to
448       those already provided.
449
450       --config file
451              Use  file  instead  of  the default configuration file, which is
452              ~/.config/enplayer/enplayer.conf.
453
454       --keymap file
455              [multi-valued] Load key bindings from file in  addition  to  the
456              (built-in  defaults  and)  bindings  loaded from the default key
457              binding file ~/.config/enplayer/input.conf.
458
459       --dump-keys binding
460              Dumps a keybinding table, where binding can be default  for  the
461              default built-in binding table, or current for the current bind‐
462              ing table obtained as combination of default and loaded from ad‐
463              ditional file(s).
464

EXAMPLES

466       The  following examples illustrate how the flexibility of the GStreamer
467       framework and configurability of enplayer  combine  to  allow  lots  of
468       tweaking  using  aforementioned  (generic) commands and options, rather
469       than a whole set of dedicated options. This is  typically  demonstrated
470       with a fragment of a configuration file and/or of a keymap file, though
471       in the former case an equivalent command line option is of course  also
472       possible.
473
474       Output (audio/video) driver selection
475
476       In  GStreamer  this  comes  down  to  selection of audio or video sink.
477       While this is usually taken care of by  playbin's  auto-plugging,  this
478       can easily be set as desired e.g. as follows.
479
480
481       [playbin]
482       video-sink = glimagesink
483       audio-sink = pulsesink
484
485
486       On  a typical Linux distribution, reasonable choices for video-sink are
487       (e.g.) glimagesink or xvimagesink, whereas (e.g.) pulsesink or alsasink
488       are typical audio-sink choices.
489
490       ALSA volume control
491
492       Continuing  on  the  previous  example, if alsasink is chosen for audio
493       output (either manually or automatically), then this typically  entails
494       softvolume control (or no volume control at all). The former uses soft‐
495       ware scaling which is not tied to any hardware control and  correspond‐
496       ing  mixer  slider.   The  entransalsavolume  element  implements  Gst‐
497       StreamVolume and maps volume control to a selected ALSA  mixer  control
498       (e.g. PCM).  It can be called into service as follows:
499
500
501       [option]
502       linear = true
503       [playbin]
504       audio-sink = alsavolume device=hw:0 control=PCM ! alsasink device=plughw:0
505
506
507       The  property values as set above are in fact the defaults and could be
508       omitted, see also entransalsavolume documentation. The alsasink proper‐
509       ty  is  set explicitly to avoid ALSA routing through PulseAudio if such
510       has been setup, but could otherwise also be omitted.
511
512       Note that entransalsavolume is part of the  entrans  plugin  collection
513       and  as such requires package installation (rather than minimal instal‐
514       lation by copying scripts).
515
516       URI Source tweaking
517
518       The --dvd-device option is an example of this category,  but  this  can
519       also  come  in  handy  when playing a live http MJPEG stream (e.g. from
520       some camera):
521
522
523       [souphttpsrc]
524       # timestamp input for proper playback downstream
525       do-timestamp = true
526       is-live = true
527
528       [multipartdemux]
529       # a reasonable assumption;
530       # and required to have no-more-pads signalled
531       single-stream = true
532
533
534       Of course, much more or other properties could be tweaked as needed.
535
536       Although preceding examples focus on playbin or source property  setup,
537       any  element within the pipeline can be adjusted, e.g.  an auto-plugged
538       decoder's properties could be fine-tuned, ...
539
540       Color balance controls
541
542       While no such support is provided by default, it can  easily  be  added
543       (and tweaked to liking) with following keymap binding example fragment:
544
545
546       F11 prop_add GstColorBalance contrast -0.1
547       F12 prop_add GstColorBalance contrast 0.1
548       F3 prop_add GstColorBalance brightness -0.1
549       F4 prop_add GstColorBalance brightness 0.1
550       F5 prop_add GstColorBalance hue -0.1
551       F6 prop_add GstColorBalance hue 0.1
552       F7 prop_add GstColorBalance saturation -0.1
553       F8 prop_add GstColorBalance saturation 0.1
554
555
556       To  reiterate,  any  element  can be located using a regular expression
557       that is matched against the element  name,  path,  factory  name,  (su‐
558       per)typename or implemented interface (and having the indicated proper‐
559       ty). The generic commands then allow setting or adjusting  the  current
560       value (by adding, multiplying or toggling).
561
562       Pipeline interaction
563
564       As  another  illustration  of the element property setting generic com‐
565       mands, let's first bring a video-filter into the pipeline:
566
567
568       [playbin]
569       video-filter = videoflip
570
571
572       Then we can steer the element at runtime with some key bindings:
573
574
575       u prop_set videoflip video-direction 0
576       d prop_set videoflip video-direction 2
577
578
579       Of course, many more variations are possible, up to using whole bins as
580       filter  elements  which  could include tee, valve, inputselector and/or
581       outputselector, all of which could be influenced  at  runtime  by  key‐
582       stroke.
583

SEE ALSO

585       GStreamer homepage ⟨http://www.gstreamer.net/⟩ , gst-launch(1), entrans
586       plugins ⟨http://gentrans.sourceforge.net/
587

AUTHOR

589       Mark Nauwelaerts <mnauw@users.sourceforge.net>
590
591
592
593                                     1.4.1                         enplayer(1)
Impressum