.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "ncplayer" "1" "v3.0.9" "" ""
.SH NAME
ncplayer - Render images and video to a terminal
.SH SYNOPSIS
\f[B]ncplayer\f[R]\ [\f[B]-h\f[R]]\ [\f[B]-V\f[R]] [\f[B]-q\f[R]]
[\f[B]-d\f[R]\ \f[B]\f[BI]delaymult\f[B]\f[R]]\ [\f[B]-l\f[R]\ \f[B]\f[BI]loglevel\f[B]\f[R]]
[\f[B]-b\f[R] \f[B]\f[BI]blitter\f[B]\f[R]] [\f[B]-s\f[R]
\f[B]\f[BI]scalemode\f[B]\f[R]] [\f[B]-k\f[R]] [\f[B]-L\f[R]]
[\f[B]-t\f[R] \f[B]\f[BI]seconds\f[B]\f[R]] [\f[B]-n\f[R]] [\f[B]-a\f[R]
\f[B]\f[BI]color\f[B]\f[R]] files
.SH DESCRIPTION
\f[B]ncplayer\f[R] uses a multimedia-enabled Notcurses to render images
and videos to a terminal.
By default, \f[B]stretch\f[R]-type scaling is used to fill the rendering
area, and the highest-quality blitter available is employed.
.SH OPTIONS
\f[B]-d\f[R] \f[B]\f[BI]delaymult\f[B]\f[R]: Apply a non-negative
rational multiplier to the delayscale.
Only applies to multiframe media such as video and animated images.
Not supported with \f[B]-k\f[R].
.PP
\f[B]-t\f[R] \f[B]\f[BI]seconds\f[B]\f[R]: Delay \f[B]seconds\f[R] after
each file.
If this option is used, the \[dq]press any key to continue\[dq] prompt
will not be displayed.
\f[B]seconds\f[R] may be any non-negative number.
.PP
\f[B]-l\f[R] \f[B]\f[BI]loglevel\f[B]\f[R]: Log between everything
(loglevel 7) and nothing (loglevel 0) to stderr.
.PP
\f[B]-s\f[R] \f[B]\f[BI]scalemode\f[B]\f[R]: Scaling mode, one of
\f[B]none\f[R], \f[B]hires\f[R], \f[B]scale\f[R], \f[B]scalehi\f[R], or
\f[B]stretch\f[R].
.PP
\f[B]-b\f[R] \f[B]\f[BI]blitter\f[B]\f[R]: Blitter, one of
\f[B]ascii\f[R], \f[B]half\f[R], \f[B]quad\f[R], \f[B]sex\f[R],
\f[B]braille\f[R], or \f[B]pixel\f[R].
.PP
\f[B]-m margins\f[R]: Define rendering margins (see below).
.PP
\f[B]-L\f[R]: Loop frames until a key is pressed.
Not supported with \f[B]-k\f[R].
.PP
\f[B]-k\f[R]: Use direct mode (see \f[B]notcurses_direct(3)\f[R]).
This will have the effect of leaving the output on-screen after program
exit, and generating it inline (rather than clearing the screen and
placing it at the top).
Not supported with \f[B]-L\f[R] or \f[B]-d\f[R].
.PP
\f[B]-q\f[R]: Print neither frame/timing information along the top of
the screen, nor the output summary on exit.
.PP
\f[B]-a\f[R]: Treat \f[B]\f[BI]color\f[B]\f[R] as if it were
transparent.
.PP
\f[B]-n\f[R]: Use non-interpolative scaling.
The result is usually less pleasing to the eye, but it doesn\[aq]t
introduce new colors.
.PP
\f[B]-V\f[R]: Print the program name and version, and exit with success.
.PP
\f[B]-h\f[R]: Print help information, and exit with success.
.PP
files: Select which files to render, and what order to render them in.
.PP
Default margins are all 0 and default scaling is \f[B]stretch\f[R].
The full rendering area will thus be used.
Using \f[B]-m\f[R], margins can be supplied.
Provide a single number to set all four margins to the same value, or
four comma-delimited values for the top, right, bottom, and left margins
respectively.
Top, right, and bottom margins are ignored when \f[B]-k\f[R] is used.
Negative margins are illegal.
.PP
Scaling mode \f[B]stretch\f[R] resizes the object to match the target
rendering area exactly.
Unless a blitter is specified with \f[B]-b\f[R], \f[B]stretch\f[R] will
use the highest-resolution blitter available.
\f[B]scale\f[R] resizes the object so that the longer edge of the
rendering area is matched exactly, and the other edge is changed to
maintain aspect ratio.
\f[B]none\f[R] uses the original image size.
Both \f[B]scale\f[R] and \f[B]none\f[R] aim for a 1:1 aspect ratio, and
will thus prefer \f[B]half\f[R] to \f[B]quad\f[R], \f[B]sex\f[R], or
\f[B]braille\f[R].
\f[B]scalehi\f[R] and \f[B]hires\f[R] use the highest-resolution blitter
available.
.PP
Blitters can be selected at runtime by pressing \[aq]0\[aq] through
\[aq]6\[aq].
\f[B]NCBLIT_DEFAULT\f[R] corresponds to \[aq]0\[aq].
The various blitters are described in \f[B]notcurses_visual(3)\f[R].
If a blitter cannot be used in the current environment, the current
blitter will be retained.
.PP
Multiframe media can be paused with space.
Press space (or any other valid control) to resume.
.SH NOTES
If you\[aq]re looking for a fast, inline image viewer for the shell, try
using \f[B]ncplayer -k -t0 -q\f[R].
.PP
Optimal display requires a terminal advertising the \f[B]rgb\f[R]
terminfo(5) capability, or that the environment variable
\f[B]COLORTERM\f[R] is defined to \f[B]24bit\f[R] (and that the terminal
honors this variable), along with a fixed-width font with good coverage
of the Unicode Block Drawing Characters.
.SH BUGS
Direct mode is kinda fundamentally suboptimal for multiframe media, and
is not yet supported with \f[B]-L\f[R] nor \f[B]-d\f[R].
Top, right, and bottom margins are ignored without warning when using
direct mode.
.SH SEE ALSO
\f[B]notcurses(3)\f[R], \f[B]notcurses_direct(3)\f[R],
\f[B]notcurses_visual(3)\f[R], \f[B]terminfo(5)\f[R],
\f[B]unicode(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.