1enplayer(1) enplayer(1)
2
6 enplayer - GStreamer media/pipeline player
7
9 enplayer [OPTION]... {--} {MEDIA}...
10
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 · 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 · 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 · 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 · 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 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
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 Without further delay, the default key bindings during playback are
57 then as follows:
58 ## 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 # (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 # (un)pause
87 p pause
88 SPACE pause
89 # (int volinc)
91 # adjust volume
92 / volume -1
93 9 volume -1
94 * volume 1
95 0 volume 1
96 # (un)mute
98 m mute
99 # cycle OSD mode
101 o osd
102 # (int inc)
104 # switch video stream
105 _ switch_video 1
106 # (int inc)
108 # switch audio stream
109 # switch_audio 1
110 # (int inc)
112 # switch subtitle stream
113 J switch_sub -1
114 j switch_sub 1
115 # toggle subtitle visibility
117 v sub_visibility
118 # cycle through aspect-ratios
120 a switch_aspect_ratio
121 # (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 # (float rate)
131 # set playback speed
132 BS speed_set 1.0
133 # (int offset_adjust_ms)
135 # adjust audio delay
136 + audio_delay 100
137 - audio_delay -100
138 # toggle repeat play of each playlist item
140 r repeat
141 # toggle looping of playlist
143 l loop
144 # toggle keyframe seeking
146 k keyframe
147 # toggle window fullscreen; only supported by toolkit backend
149 f fullscreen
150 # (int displaysize)
152 # take a .png screenshot with raw video size or displayed size
153 s screenshot 0
154 S screenshot 1
155 # (int steps)
157 # frame step
158 . frame_step 1
159 6 frame_step 1
160 4 frame_step -1
161 # (int direction)
163 # keyframe step (positive next, negative previous)
164 8 keyframe_step 1
165 2 keyframe_step -1
166 # (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 # show help (man page)
174 F1 help
175 # (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 # (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 # (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 # (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 # quit
201 q quit
202 ESC quit
203 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 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 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 · video frame and display size, as well as display aspect-ratio
220 · audio-video offset (as set by audio_delay command in the above list)
222 · playback (segment) rate
224 · 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 · clip duration (as determined by GST_QUERY_POSITION)
232 · clip position in percentage (ratio of foregoing items)
234 · current video, audio and subtitle stream (where applicable)
236 · current audio volume (on cubic or linear scale)
238 · a number of status flags displayed in bold if enabled and prefixed
240 with ! if disabled;
241 S whether clip is seekable (GST_QUERY_SEEKING),
243 K whether keyframe seeking is active,
245 R whether repeat play is active,
247 L whether loop play is active,
249 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
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 · 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 · 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 -h, --help
278 Show a brief help message.
279 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 --no-audio, --no-video, --no-sub, --no-video
287 [non-custom only] Disable rendering of the specified stream
288 type.
289 As an implementation note, this simply masks the corresponding
291 playbin flags (after any custom flag setting has been applied).
292 --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 --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 --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 --dvd-device device
311 Specifies the dvd device or file.
312 Technically, this is merely a convenient shorthand for
314 --set-prop dvdreadsrc:dvd-device:device --set-prop rsndvd‐
315 bin:dvd-device:device
316 --geometry WIDTHxHEIGHT+XOFF+YOFF
318 A standard XWindows geometry specification, see e.g. X(1) for
319 details.
320 --disable-screensaver method
322 Specify the method to disable screensaver (and suspend) during
323 playback. Possible choices for method are:
324 none No screensaver disabling
326 dbus Use a (heuristically determined) DBus interface
328 xdg Use xdg-screensaver
330 auto Try the dbus way and fallback to xdg
332 --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 none Ensures a pristine pipeline with no OSD whatsoever
340 ascii OSD using only ASCII text
342 standard
344 OSD using Unicode character set text
345 graphic
347 OSD as with standard, but also using a graphic slider
348 --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 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 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 --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 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 · element's factory name.prop
384 · element's name.prop
386 · element's path name.prop
388 In each case, the last part is omitted if there is no prop in the con‐
390 text in question.
391 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 -m Output messages posted on the pipeline's bus
398 --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 -v Provide output on property changes of the pipeline's elements.
405 This output can be filtered using -x
406 -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 -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 --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 --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 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 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 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 --config file
451 Use file instead of the default configuration file, which is
452 ~/.config/enplayer/enplayer.conf.
453 --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 --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
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 Output (audio/video) driver selection
475 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 [playbin]
482 video-sink = glimagesink
483 audio-sink = pulsesink
484 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 ALSA volume control
491 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 [option]
502 linear = true
503 [playbin]
504 audio-sink = alsavolume device=hw:0 control=PCM ! alsasink device=plughw:0
505 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 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 URI Source tweaking
517 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 [souphttpsrc]
524 # timestamp input for proper playback downstream
525 do-timestamp = true
526 is-live = true
527 [multipartdemux]
529 # a reasonable assumption;
530 # and required to have no-more-pads signalled
531 single-stream = true
532 Of course, much more or other properties could be tweaked as needed.
535 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 Color balance controls
541 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 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 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 Pipeline interaction
563 As another illustration of the element property setting generic com‐
565 mands, let's first bring a video-filter into the pipeline:
566 [playbin]
569 video-filter = videoflip
570 Then we can steer the element at runtime with some key bindings:
573 u prop_set videoflip video-direction 0
576 d prop_set videoflip video-direction 2
577 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
585 GStreamer homepage ⟨http://www.gstreamer.net/⟩ , gst-launch(1), entrans
586 plugins ⟨http://gentrans.sourceforge.net/⟩
587
589 Mark Nauwelaerts <mnauw@users.sourceforge.net>
590 1.4.0 enplayer(1)