Name

enplayer — GStreamer media/pipeline player

Synopsis

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

Description

enplayer is a GStreamer based media player implemented as a python script. While it may or may not be unique in that, it has been made with the following goals in mind;

  • plain-and-simple, e.g. no GUI trimmings, other than (of course) a video window also offering a minimal OSD (whenever possible). On the other hand, a small codebase that runs simply as a standalone script and needs no special installation, other than having the sibling entrans script alongside for some shared support code.

  • to serve as a key-binding layer that maps some input key to GStreamer API in a flexible and configurable way. In that regard, it aims to be a python based interactive gst-launch(1) (with controllable key-binding mapping keystrokes to commands that allow e.g. setting any pipeline element property at runtime).

  • to suit both regular desktop use as well as a developer diagnostic tool, e.g. runnable on an embedded target controlled over ssh command line (and, in fact, it evolved from such a tool/script). In particular, it has only a limited set of python module dependencies, and will enable features and capabilities depending on (runtime) available python bindings/modules (and their native library implementations). Moreover, it does not favour or expect any particular videosink, though some features require proper support for GstVideoOverlay (as is typically the case anyway).

  • to support playbin based dynamic pipelines, but to degrade gracefully and still provide as much features as possible for custom specified pipelines (in advanced developer use cases)

At a minimum, it requires a GStreamer installation with a convenient set of plugins along with gobject-introspection data for GStreamer core. The media types supported by enplayer are determined solely by the set of plugins, and both the default set and additional availability likely depend on the particular distribution.

Usage

For simple media playing, it accepts a list of media URIs and will play each in turn, where a simple file path is also accepted (and converted into a file:// URI). Again, the set of supported URIs is determined by the GStreamer installation, but likely includes http://, rtsp://, dvd://. A much more impressive listing could be provided here, but e.g. gst-inspect(1)'s -u option will show what is available.

Without further delay, the default key bindings during playback are then as follows:

## Enplayer input control file
## 
## Key bindings can be added or redefined here
## Functions are documented along with arguments
## (use ignore as function to unbind a key)
## 
## Bindings are added to default binding table from following files:
##   ~/.config/enplayer/input.conf
## 

# (int seconds)
# relative seek
v seek 10
V seek 60
b seek -10
B seek -60
g seek 300
G seek 600
n seek -300
N seek -600
RIGHT seek 10
LEFT seek -10
UP seek 60
DOWN seek -60
PGUP seek 600
PGDOWN seek -600

# (un)pause
p pause
SPACE pause

# (int volinc)
# adjust volume
/ volume -1
9 volume -1
* volume 1
0 volume 1

# (un)mute
m mute

# cycle OSD mode
o osd

# (int inc)
# switch video stream
_ switch_video 1

# (int inc)
# switch audio stream
# switch_audio 1

# (int inc)
# switch subtitle stream
h switch_sub -1
j switch_sub 1

# cycle through aspect-ratios
a switch_aspect_ratio

# (float rate)
# scale playback speed
[ speed_mult 0.9091
] speed_mult 1.1
{ speed_mult 0.5
} speed_mult 2.0
x speed_mult -1.0

# (float rate)
# set playback speed
BS speed_set 1.0

# (int offset_adjust_ms)
# adjust audio delay
+ audio_delay 100
- audio_delay -100

# toggle repeat play of each playlist item
r repeat

# toggle looping of playlist
l loop

# toggle keyframe seeking
k keyframe

# toggle window fullscreen; only supported by toolkit backend
f fullscreen

# (int displaysize)
# take a .png screenshot with raw video size or displayed size
s screenshot 0
S screenshot 1

# (int steps)
# frame step
. frame_step 1
6 frame_step 1
4 frame_step -1

# (int direction)
# keyframe step (positive next, negative previous)
8 keyframe_step 1
2 keyframe_step -1

# (int inc, int overboundary=0)
# skip to previous/next entry in playlist possibly going over the begin/end
< pt_step -1
> pt_step 1
ENTER pt_step 1 1

# show help (man page)
F1 help

# (str elregexp, str prop, str value)
# find an element el by matching elregexp against its name, path string,
# factory name, any supertype or any implemented interface and
# set property prop of el to value
CTRL-2 prop_set fillel fillprop 

# (str elregexp, str prop, float term)
# find an element el by matching elregexp against its name, path string,
# factory name, any supertype or any implemented interface and
# add term to property prop of el
CTRL-3 prop_add fillel fillprop 0

# (str elregexp, str prop, float factor)
# find an element el by matching elregexp against its name, path string,
# factory name, any supertype or any implemented interface and
# mult property prop of el with factor
ALT-4 prop_mult fillel fillprop 1.0

# (str elregexp, str prop)
# find an element el by matching elregexp against its name, path string,
# factory name, any supertype or any implemented interface and
# toggle property prop of el
ALT-5 prop_toggle fillel fillprop

# special
X special

# quit
q quit
ESC quit

One might notice that these default bindings closely match those of enplayer's phonetic precursor. The key bindings can easily be tweaked to taste by placing definitions such as the above in e.g. ~/.config/enplayer/input.conf.

If some desired function/command seems missing from the above list, then also have a look at “Examples” where some common functions are implemented using generic commands.

If enplayer is started from terminal (command line), then at the start of playing each clip some information is displayed including the discovered streams along with tag metadata. In addition, status lines updated during playback provide following information:

  • video frame and display size, as well as display aspect-ratio

  • audio-video offset (as set by audio_delay command in the above list)

  • playback (segment) rate

  • current position (as determined by GST_QUERY_POSITION). In paused state, however, position is given by last video sample's stream time. Also, a + prefix is added if the latter is non-trivial, i.e. not equal to the sample buffer's PTS, and a frame number is shown as well (simply derived linearly based on discovered framerate).

  • clip duration (as determined by GST_QUERY_POSITION)

  • clip position in percentage (ratio of foregoing items)

  • current video, audio and subtitle stream (where applicable)

  • current audio volume (on cubic or linear scale)

  • a number of status flags displayed in bold if enabled and prefixed with ! if disabled;

    S

    whether clip is seekable (GST_QUERY_SEEKING),

    K

    whether keyframe seeking is active,

    R

    whether repeat play is active,

    L

    whether loop play is active,

When playing a media URI, the pipeline is playbin based. However, as alluded to above, a custom pipeline can also be specified while retaining as much player functionality as possible, e.g. (un)pause, seek, step operations and providing information on caps, tags, duration, position etc (though obviously, there are no evident/defined streams to switch between for example).

Options

As will be noticed, some options are shared with and influenced by the quintessential diagnostic tool gst-launch(1) or enplayer's sibling entrans, although quite some others are more specific to the setting here. In any case, enplayer accepts the options presented in the following sections, most of which have shortname (one-letter) or longname forms. The ordering of the options is not strict, and options can be single-valued or multi-valued.

  • In the former case, which is the default unless otherwise indicated below, only the value given last is retained. In particular, this includes boolean options.

  • Otherwise, for multi-valued options, all values given are taken into consideration. In these cases, it may sometimes also be possible to pass several values per single option occurrence, by comma-separating these values as indicated in each such case below. This will typically be the case in those instances where there can be no ambiguity since the supplied value does not include free-text.

-h, --help

Show a brief help message.

Basic options

Most of the following options apply whether or not the pipeline is custom. However, in either case, some depend on enplayer successfully finding the element serving as video sink (as it automagically tries to do) or providing GstStreamVolume interface.

--no-audio, --no-video, --no-sub, --no-video

[non-custom only] Disable rendering of the specified stream type.

As an implementation note, this simply masks the corresponding playbin flags (after any custom flag setting has been applied).

--aspect-ratio W:H

enplayer holds a list of standard (display) aspect-ratios that can be cycled through (media-specified, 4:3 or 16:9). This options adds the specified ratio to the list and makes it the active entry (thereby forcing the specified display aspect-ratio).

--screenshot-file file

Filename to save (png) screenshot to when requested, subject to having [PTS] replaced by the frame's (buffer) (presentation) timestamp.

--linear

Volume (percentage or slider) is usually displayed on a cubic scale (as customary in the PulseAudio framework). This option will use a linear scale instead (as might be found in ALSA slider display). See also example Example 2.12, “ALSA volume control”.

--dvd-device device

Specifies the dvd device or file.

Technically, this is merely a convenient shorthand for --set-prop dvdreadsrc:dvd-device:device --set-prop rsndvdbin:dvd-device:device

--geometry WIDTHxHEIGHT+XOFF+YOFF

A standard XWindows geometry specification, see e.g. X(1) for details.

--disable-screensaver method

Specify the method to disable screensaver (and suspend) during playback. Possible choices for method are:

none
No screensaver disabling
dbus
Use a (heuristically determined) DBus interface
xdg
Use xdg-screensaver
auto
Try the dbus way and fallback to xdg

--osd method

[non-custom only] As enplayer is sink-agnostic, a minimal OSD is implemented by composing some standard elements into a bin that is used as video filter on playbin (inserted after a user-set video filter, if any). Possible choices for method are:

none
Ensures a pristine pipeline with no OSD whatsoever
ascii
OSD using only ASCII text
standard
OSD using Unicode character set text
graphic
OSD as with standard, but also using a graphic slider

--set-prop element:prop:value

Sets property prop of element to value, where element can either be a factory name, or the name or full path-string of a specific element. Note that a value given for a property within a (custom) pipeline description will override any value provided this way. More precisely, this option will not set a property if it is already set to a non-default value.

The rank of an element (as a plugin feature), which (a.o.) determines whether/how it is used for auto-plugging (by playbin and friends) is considered as a pseudo-property pf_rank and can therefore be set in this way as well to influence dynamic pipeline construction.

Advanced options

Many of the following options are of gst-launch(1) descent and apply both to a custom or a dynamically constructed player pipeline.

--no-toolkit

enplayer normally tries to setup a window of its own and then uses GstVideoOverlay interface to pass this along suitably. This option disables such setup, so video window management is entirely up to a video sink (as in gst-launch(1) case). Since the latter is then not enplayer's business, it follows there is no window geometry management (e.g. no fullscreen) and that key events are not received from the video window (navigation messages are then used instead, typically with little or no modifier key consideration).

In the following, proppattern is a regular expression that will be matched against a combination of an element and (optionally) one of its properties prop. More precisely, this combination matches if the regular expression matches any of the following:

  • element's factory name.prop

  • element's name.prop

  • element's path name.prop

In each case, the last part is omitted if there is no prop in the context in question.

Similarly, msgpattern is matched against expressions as above, but with prop replaced by message type name.message structure name. Again, in each case, the last part is omitted if there is no structure for the message in question.

-m

Output messages posted on the pipeline's bus

--ignore-msg msgpattern[,…] , --display-msg msgpattern[,…]

[multi-valued] If message reporting is enabled by -m, only report on those that match --display-msg or do not match --ignore-msg

-v

Provide output on property changes of the pipeline's elements. This output can be filtered using -x

-x proppattern[,…] , --exclude proppattern[,…] , --include proppattern[,…]

[multi-valued] If property change reporting is enabled by -v, only report those on properties that match --include or do not match --exclude

-p, --prop

Also report a summary of properties that have been notify'ed (to a non-default value) during start-up of media playback

--display-prop proppattern[,…] , --ignore-prop proppattern[,…]

[multi-valued] An element's property (value) is reported at start-up if and only if it matches an expression given in --display-prop or its value differs from the default value and it does not match --ignore-prop.

--raw

Switches into custom pipeline mode, where all remaining arguments are collected and whitespace-joined into a pipeline description (in the usual gst-launch(1) way).

Configuration options

Each enplayer option —be it one affecting enplayer's run-time behaviour or affecting pipeline element (properties)— can also be provided on a more permanent basis using a configuration file. Such a file consists of sections, led by a [section] header and followed by name: value entries, name=value is also accepted. Note that leading whitespace is removed from values. Lines beginning with # or ; are ignored and may be used to provide comments.

In the special section [options], each entry name: value is equivalent to providing --name value on the command-line, where name must be an option's longname. If the option is multi-valued and does not accept a comma-separated list of values, then name may also have _0 or _1 (and so forth) appended to it. The name of any other section is interpreted as an element, with each entry providing a value for a property. Otherwise put, each prop: value in a section [element] is equivalent to mentioning it in --set-prop as element:prop:value

Any setting provided on the command line for a single-valued option (e.g. a boolean option) overrides a similar value given in a configuration file, whereas values provided for multi-valued ones append to those already provided.

--config file

Use file instead of the default configuration file, which is ~/.config/enplayer/enplayer.conf.

--keymap file

[multi-valued] Load key bindings from file in addition to the (built-in defaults and) bindings loaded from the default key binding file ~/.config/enplayer/input.conf.

--dump-keys binding

Dumps a keybinding table, where binding can be default for the default built-in binding table, or current for the current binding table obtained as combination of default and loaded from additional file(s).

Examples

The following examples illustrate how the flexibility of the GStreamer framework and configurability of enplayer combine to allow lots of tweaking using aforementioned (generic) commands and options, rather than a whole set of dedicated options. This is typically demonstrated with a fragment of a configuration file and/or of a keymap file, though in the former case an equivalent command line option is of course also possible.

Example 2.11. Output (audio/video) driver selection

In GStreamer this comes down to selection of audio or video sink. While this is usually taken care of by playbin's auto-plugging, this can easily be set as desired e.g. as follows.

[playbin]
video-sink = glimagesink
audio-sink = pulsesink

On a typical Linux distribution, reasonable choices for video-sink are (e.g.) glimagesink or xvimagesink, whereas (e.g.) pulsesink or alsasink are typical audio-sink choices.


Example 2.12. ALSA volume control

Continuing on the previous example, if alsasink is chosen for audio output (either manually or automatically), then this typically entails softvolume control (or no volume control at all). The former uses software scaling which is not tied to any hardware control and corresponding mixer slider. The entransalsavolume element implements GstStreamVolume and maps volume control to a selected ALSA mixer control (e.g. PCM). It can be called into service as follows:

[option]
linear = true
[playbin]
audio-sink = alsavolume device=hw:0 control=PCM ! alsasink device=plughw:0

The property values as set above are in fact the defaults and could be omitted, see also entransalsavolume documentation. The alsasink property is set explicitly to avoid ALSA routing through PulseAudio if such has been setup, but could otherwise also be omitted.

Note that entransalsavolume is part of the entrans plugin collection and as such requires package installation (rather than minimal installation by copying scripts).


Example 2.13. URI Source tweaking

The --dvd-device option is an example of this category, another one is provided below:

[rtspsrc]
# custom proxy
proxy = http://myproxy
# if in developer mo(o)d(e)
debug = true
# handle broken sender
short-header = true

Of course, much more or other properties could be tweaked as needed.

Although preceding examples focus on playbin or source property setup, any element within the pipeline can be adjusted, e.g. an auto-plugged decoder's properties could be fine-tuned, …


Example 2.14. Color balance controls

While no such support is provided by default, it can easily be added (and tweaked to liking) with following keymap binding example fragment:

F11 prop_add GstColorBalance contrast -0.1
F12 prop_add GstColorBalance contrast 0.1
F3 prop_add GstColorBalance brightness -0.1
F4 prop_add GstColorBalance brightness 0.1
F5 prop_add GstColorBalance hue -0.1
F6 prop_add GstColorBalance hue 0.1
F7 prop_add GstColorBalance saturation -0.1
F8 prop_add GstColorBalance saturation 0.1

To reiterate, any element can be located using a regular expression that is matched against the element name, path, factory name, (super)typename or implemented interface (and having the indicated property). The generic commands then allow setting or adjusting the current value (by adding, multiplying or toggling).


Example 2.15. Pipeline interaction

As another illustration of the element property setting generic commands, let's first bring a video-filter into the pipeline:

[playbin]
video-filter = videoflip

Then we can steer the element at runtime with some key bindings:

u prop_set videoflip video-direction 0
d prop_set videoflip video-direction 2

Of course, many more variations are possible, up to using whole bins as filter elements which could include tee, valve, inputselector and/or outputselector, all of which could be influenced at runtime by keystroke.


See Also

GStreamer homepage, gst-launch(1), entrans plugins

Author

Mark Nauwelaerts