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 # special
201 Z special
202 # quit
204 q quit
205 ESC quit
206 One might notice that these default bindings closely match those of en‐
209 player's phonetic precursor. The key bindings can easily be tweaked to
210 taste by placing definitions such as the above in e.g. ~/.config/en‐
211 player/input.conf.
212 If some desired function/command seems missing from the above list,
214 then also have a look at EXAMPLES where some common functions are im‐
215 plemented using generic commands.
216 If enplayer is started from terminal (command line), then at the start
218 of playing each clip some information is displayed including the dis‐
219 covered streams along with tag metadata. In addition, status lines up‐
220 dated during playback provide following information:
221 · video frame and display size, as well as display aspect-ratio
223 · audio-video offset (as set by audio_delay command in the above list)
225 · playback (segment) rate
227 · current position (as determined by GST_QUERY_POSITION). In paused
229 state, however, position is given by last video sample's stream time.
230 Also, a + prefix is added if the latter is non-trivial, i.e. not
231 equal to the sample buffer's PTS, and a frame number is shown as well
232 (simply derived linearly based on discovered framerate).
233 · clip duration (as determined by GST_QUERY_POSITION)
235 · clip position in percentage (ratio of foregoing items)
237 · current video, audio and subtitle stream (where applicable)
239 · current audio volume (on cubic or linear scale)
241 · a number of status flags displayed in bold if enabled and prefixed
243 with ! if disabled;
244 S whether clip is seekable (GST_QUERY_SEEKING),
246 K whether keyframe seeking is active,
248 R whether repeat play is active,
250 L whether loop play is active,
252 When playing a media URI, the pipeline is playbin based. However, as
254 alluded to above, a custom pipeline can also be specified while retain‐
255 ing as much player functionality as possible, e.g. (un)pause, seek,
256 step operations and providing information on caps, tags, duration, po‐
257 sition etc (though obviously, there are no evident/defined streams to
258 switch between for example).
259
261 As will be noticed, some options are shared with and influenced by the
262 quintessential diagnostic tool gst-launch(1) or enplayer's sibling en‐
263 trans, although quite some others are more specific to the setting
264 here. In any case, enplayer accepts the options presented in the fol‐
265 lowing sections, most of which have shortname (one-letter) or longname
266 forms. The ordering of the options is not strict, and options can be
267 single-valued or multi-valued.
268 · In the former case, which is the default unless otherwise indicated
270 below, only the value given last is retained. In particular, this
271 includes boolean options.
272 · Otherwise, for multi-valued options, all values given are taken into
274 consideration. In these cases, it may sometimes also be possible to
275 pass several values per single option occurrence, by comma-separating
276 these values as indicated in each such case below. This will typical‐
277 ly be the case in those instances where there can be no ambiguity
278 since the supplied value does not include free-text.
279 -h, --help
281 Show a brief help message.
282 BASIC OPTIONS
284 Most of the following options apply whether or not the pipeline is cus‐
285 tom. However, in either case, some depend on enplayer successfully
286 finding the element serving as video sink (as it automagically tries to
287 do) or providing GstStreamVolume interface.
288 --no-audio, --no-video, --no-sub, --no-video
290 [non-custom only] Disable rendering of the specified stream
291 type.
292 As an implementation note, this simply masks the corresponding
294 playbin flags (after any custom flag setting has been applied).
295 --aspect-ratio W:H
297 enplayer holds a list of standard (display) aspect-ratios that
298 can be cycled through (media-specified, 4:3 or 16:9). This op‐
299 tions adds the specified ratio to the list and makes it the ac‐
300 tive entry (thereby forcing the specified display aspect-ratio).
301 --screenshot-file file
303 Filename to save (png) screenshot to when requested, subject to
304 having [PTS] replaced by the frame's (buffer) (presentation)
305 timestamp.
306 --linear
308 Volume (percentage or slider) is usually displayed on a cubic
309 scale (as customary in the PulseAudio framework). This option
310 will use a linear scale instead (as might be found in ALSA slid‐
311 er display). See also example ALSA volume control.
312 --dvd-device device
314 Specifies the dvd device or file.
315 Technically, this is merely a convenient shorthand for
317 --set-prop dvdreadsrc:dvd-device:device --set-prop rsndvd‐
318 bin:dvd-device:device
319 --geometry WIDTHxHEIGHT+XOFF+YOFF
321 A standard XWindows geometry specification, see e.g. X(1) for
322 details.
323 --disable-screensaver method
325 Specify the method to disable screensaver (and suspend) during
326 playback. Possible choices for method are:
327 none No screensaver disabling
329 dbus Use a (heuristically determined) DBus interface
331 xdg Use xdg-screensaver
333 auto Try the dbus way and fallback to xdg
335 --osd method
337 [non-custom only] As enplayer is sink-agnostic, a minimal OSD is
338 implemented by composing some standard elements into a bin that
339 is used as video filter on playbin (inserted after a user-set
340 video filter, if any). Possible choices for method are:
341 none Ensures a pristine pipeline with no OSD whatsoever
343 ascii OSD using only ASCII text
345 standard
347 OSD using Unicode character set text
348 graphic
350 OSD as with standard, but also using a graphic slider
351 --set-prop element:prop:value
353 Sets property prop of element to value, where element can either
354 be a factory name, or the name or full path-string of a specific
355 element. Note that a value given for a property within a (cus‐
356 tom) pipeline description will override any value provided this
357 way. More precisely, this option will not set a property if it
358 is already set to a non-default value.
359 The rank of an element (as a plugin feature), which (a.o.) de‐
361 termines whether/how it is used for auto-plugging (by playbin
362 and friends) is considered as a pseudo-property pf_rank and can
363 therefore be set in this way as well to influence dynamic pipe‐
364 line construction.
365 ADVANCED OPTIONS
367 Many of the following options are of gst-launch(1) descent and apply
368 both to a custom or a dynamically constructed player pipeline.
369 --no-toolkit
371 enplayer normally tries to setup a window of its own and then
372 uses GstVideoOverlay interface to pass this along suitably.
373 This option disables such setup, so video window management is
374 entirely up to a video sink (as in gst-launch(1) case). Since
375 the latter is then not enplayer's business, it follows there is
376 no window geometry management (e.g. no fullscreen) and that key
377 events are not received from the video window (navigation mes‐
378 sages are then used instead, typically with little or no modifi‐
379 er key consideration).
380 In the following, proppattern is a regular expression that will be
382 matched against a combination of an element and (optionally) one of its
383 properties prop. More precisely, this combination matches if the regu‐
384 lar expression matches any of the following:
385 · element's factory name.prop
387 · element's name.prop
389 · element's path name.prop
391 In each case, the last part is omitted if there is no prop in the con‐
393 text in question.
394 Similarly, msgpattern is matched against expressions as above, but with
396 prop replaced by message type name.message structure name. Again, in
397 each case, the last part is omitted if there is no structure for the
398 message in question.
399 -m Output messages posted on the pipeline's bus
401 --ignore-msg msgpattern[,...] , --display-msg msgpattern[,...]
403 [multi-valued] If message reporting is enabled by -m, only re‐
404 port on those that match --display-msg or do not match --ig‐
405 nore-msg
406 -v Provide output on property changes of the pipeline's elements.
408 This output can be filtered using -x
409 -x proppattern[,...] , --exclude proppattern[,...] , --include proppat‐
411 tern[,...]
412 [multi-valued] If property change reporting is enabled by -v,
413 only report those on properties that match --include or do not
414 match --exclude
415 -p, --prop
417 Also report a summary of properties that have been notify'ed (to
418 a non-default value) during start-up of media playback
419 --display-prop proppattern[,...] , --ignore-prop proppattern[,...]
421 [multi-valued] An element's property (value) is reported at
422 start-up if and only if it matches an expression given in --dis‐
423 play-prop or its value differs from the default value and it
424 does not match --ignore-prop.
425 --raw Switches into custom pipeline mode, where all remaining argu‐
427 ments are collected and whitespace-joined into a pipeline de‐
428 scription (in the usual gst-launch(1) way).
429 CONFIGURATION OPTIONS
431 Each enplayer option —be it one affecting enplayer's run-time behaviour
432 or affecting pipeline element (properties)— can also be provided on a
433 more permanent basis using a configuration file. Such a file consists
434 of sections, led by a [section] header and followed by name: value en‐
435 tries, name=value is also accepted. Note that leading whitespace is
436 removed from values. Lines beginning with # or ; are ignored and may
437 be used to provide comments.
438 In the special section [options], each entry name: value is equivalent
440 to providing --name value on the command-line, where name must be an
441 option's longname. If the option is multi-valued and does not accept a
442 comma-separated list of values, then name may also have _0 or _1 (and
443 so forth) appended to it. The name of any other section is interpreted
444 as an element, with each entry providing a value for a property. Oth‐
445 erwise put, each prop: value in a section [element] is equivalent to
446 mentioning it in --set-prop as element:prop:value
447 Any setting provided on the command line for a single-valued option
449 (e.g. a boolean option) overrides a similar value given in a configura‐
450 tion file, whereas values provided for multi-valued ones append to
451 those already provided.
452 --config file
454 Use file instead of the default configuration file, which is
455 ~/.config/enplayer/enplayer.conf.
456 --keymap file
458 [multi-valued] Load key bindings from file in addition to the
459 (built-in defaults and) bindings loaded from the default key
460 binding file ~/.config/enplayer/input.conf.
461 --dump-keys binding
463 Dumps a keybinding table, where binding can be default for the
464 default built-in binding table, or current for the current bind‐
465 ing table obtained as combination of default and loaded from ad‐
466 ditional file(s).
467
469 The following examples illustrate how the flexibility of the GStreamer
470 framework and configurability of enplayer combine to allow lots of
471 tweaking using aforementioned (generic) commands and options, rather
472 than a whole set of dedicated options. This is typically demonstrated
473 with a fragment of a configuration file and/or of a keymap file, though
474 in the former case an equivalent command line option is of course also
475 possible.
476 Output (audio/video) driver selection
478 In GStreamer this comes down to selection of audio or video sink.
480 While this is usually taken care of by playbin's auto-plugging, this
481 can easily be set as desired e.g. as follows.
482 [playbin]
485 video-sink = glimagesink
486 audio-sink = pulsesink
487 On a typical Linux distribution, reasonable choices for video-sink are
490 (e.g.) glimagesink or xvimagesink, whereas (e.g.) pulsesink or alsasink
491 are typical audio-sink choices.
492 ALSA volume control
494 Continuing on the previous example, if alsasink is chosen for audio
496 output (either manually or automatically), then this typically entails
497 softvolume control (or no volume control at all). The former uses soft‐
498 ware scaling which is not tied to any hardware control and correspond‐
499 ing mixer slider. The entransalsavolume element implements Gst‐
500 StreamVolume and maps volume control to a selected ALSA mixer control
501 (e.g. PCM). It can be called into service as follows:
502 [option]
505 linear = true
506 [playbin]
507 audio-sink = alsavolume device=hw:0 control=PCM ! alsasink device=plughw:0
508 The property values as set above are in fact the defaults and could be
511 omitted, see also entransalsavolume documentation. The alsasink proper‐
512 ty is set explicitly to avoid ALSA routing through PulseAudio if such
513 has been setup, but could otherwise also be omitted.
514 Note that entransalsavolume is part of the entrans plugin collection
516 and as such requires package installation (rather than minimal instal‐
517 lation by copying scripts).
518 URI Source tweaking
520 The --dvd-device option is an example of this category, but this can
522 also come in handy when playing a live http MJPEG stream (e.g. from
523 some camera):
524 [souphttpsrc]
527 # timestamp input for proper playback downstream
528 do-timestamp = true
529 is-live = true
530 [multipartdemux]
532 # a reasonable assumption;
533 # and required to have no-more-pads signalled
534 single-stream = true
535 Of course, much more or other properties could be tweaked as needed.
538 Although preceding examples focus on playbin or source property setup,
540 any element within the pipeline can be adjusted, e.g. an auto-plugged
541 decoder's properties could be fine-tuned, ...
542 Color balance controls
544 While no such support is provided by default, it can easily be added
546 (and tweaked to liking) with following keymap binding example fragment:
547 F11 prop_add GstColorBalance contrast -0.1
550 F12 prop_add GstColorBalance contrast 0.1
551 F3 prop_add GstColorBalance brightness -0.1
552 F4 prop_add GstColorBalance brightness 0.1
553 F5 prop_add GstColorBalance hue -0.1
554 F6 prop_add GstColorBalance hue 0.1
555 F7 prop_add GstColorBalance saturation -0.1
556 F8 prop_add GstColorBalance saturation 0.1
557 To reiterate, any element can be located using a regular expression
560 that is matched against the element name, path, factory name, (su‐
561 per)typename or implemented interface (and having the indicated proper‐
562 ty). The generic commands then allow setting or adjusting the current
563 value (by adding, multiplying or toggling).
564 Pipeline interaction
566 As another illustration of the element property setting generic com‐
568 mands, let's first bring a video-filter into the pipeline:
569 [playbin]
572 video-filter = videoflip
573 Then we can steer the element at runtime with some key bindings:
576 u prop_set videoflip video-direction 0
579 d prop_set videoflip video-direction 2
580 Of course, many more variations are possible, up to using whole bins as
583 filter elements which could include tee, valve, inputselector and/or
584 outputselector, all of which could be influenced at runtime by key‐
585 stroke.
586
588 GStreamer homepage ⟨http://www.gstreamer.net/⟩ , gst-launch(1), entrans
589 plugins ⟨http://gentrans.sourceforge.net/⟩
590
592 Mark Nauwelaerts <mnauw@users.sourceforge.net>
593 1.2.2 enplayer(1)