enplayer — GStreamer media/pipeline player
enplayer [OPTION...] {--} {MEDIA...}
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.
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;
whether clip is seekable (GST_QUERY_SEEKING),
whether keyframe seeking is active,
whether repeat play is active,
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).
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, --helpShow a brief help message.
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:Henplayer 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.
--linearVolume (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 deviceSpecifies 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+YOFFA 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:
nonedbusxdgautodbus 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:
noneasciistandardgraphicstandard, 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.
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.
-mOutput 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, --propAlso 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.
--rawSwitches into custom pipeline mode, where all remaining arguments are collected and whitespace-joined into a pipeline description (in the usual gst-launch(1) way).
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 -- on the command-line,
where name
valuename 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
“[”
is equivalent to mentioning it in element]--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).
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.