2021-01-18 19:22:54 +00:00
% ncplayer(1)
2020-01-14 20:50:16 +00:00
% nick black < nickblack @ linux . com >
2021-08-22 20:08:03 +00:00
% v2.3.17
2020-01-14 20:50:16 +00:00
# NAME
2021-01-18 19:22:54 +00:00
ncplayer - Render images and video to a terminal
2020-01-14 20:50:16 +00:00
# SYNOPSIS
2021-06-22 13:49:48 +00:00
**ncplayer** ** *delaymult***] ** *loglevel***] [**-b** ** *blitter***] [**-s** ** *scalemode***] [**-k**] [**-L**] [**-t** ** *seconds***] [**-n**] [**-a** ** *color***] files
2020-01-14 20:50:16 +00:00
# DESCRIPTION
2021-01-18 19:22:54 +00:00
**ncplayer** uses a multimedia-enabled Notcurses to render images and videos to a
terminal. By default, **stretch** -type scaling is used to fill the rendering
2021-02-27 21:06:31 +00:00
area, and the **sex** -type blitter is used (where known to work well) for a
2021-01-18 19:22:54 +00:00
3x2→1 mapping from pixels to cells. In a terminal that doesn't support Unicode
13 sextants, the **quadblitter** is used instead.
2020-01-14 20:50:16 +00:00
# OPTIONS
2020-12-18 23:29:04 +00:00
**-d** ** *delaymult***: Apply a non-negative rational multiplier to the delayscale.
2021-02-15 00:23:51 +00:00
Only applies to multiframe media such as video and animated images. Not supported with ** -k**.
2020-01-14 20:50:16 +00:00
2020-12-18 23:29:04 +00:00
**-t** ** *seconds***: Delay **seconds** after each file. If this option is used,
the "press any key to continue" prompt will not be displayed. **seconds** may
be any non-negative number.
2020-01-14 20:50:16 +00:00
2021-08-04 18:59:37 +00:00
**-l** ** *loglevel***: Log between everything (loglevel 7) and nothing (loglevel 0) to stderr.
2020-01-17 09:31:46 +00:00
2020-12-25 23:25:44 +00:00
**-s** ** *scalemode***: Scaling mode, one of **none** , **hires** , **scale** , **scalehi** , or **stretch** .
2020-12-18 23:29:04 +00:00
2021-02-27 21:06:31 +00:00
**-b** ** *blitter***: Blitter, one of **ascii** , **half** , **quad** , **sex** , **braille** , or **pixel** .
2020-10-17 23:52:19 +00:00
2020-04-29 07:24:11 +00:00
**-m margins**: Define rendering margins (see below).
2021-02-15 00:23:51 +00:00
**-L**: Loop frames until a key is pressed. Not supported with ** -k**.
2020-10-21 03:49:09 +00:00
2021-02-15 00:23:51 +00:00
**-k**: Use direct mode (see **notcurses_direct(3)** ). 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 ** -L** or ** -d**.
2020-04-29 07:08:21 +00:00
2021-02-09 23:50:20 +00:00
**-q**: Print neither frame/timing information along the top of the screen, nor the output summary on exit.
2020-10-18 22:46:04 +00:00
2021-06-22 13:49:48 +00:00
**-a**: Treat ** *color*** as if it were transparent.
2021-04-10 15:41:31 +00:00
2021-06-09 07:21:39 +00:00
**-n**: Use non-interpolative scaling. The result is usually less pleasing to the eye, but it doesn't introduce new colors.
2020-12-31 07:28:47 +00:00
**-V**: Print the program name and version, and exit with success.
2020-10-18 22:46:04 +00:00
**-h**: Print help information, and exit with success.
2020-01-14 20:50:16 +00:00
files: Select which files to render, and what order to render them in.
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
Default margins are all 0 and default scaling is **stretch** . The full
rendering area will thus be used. Using ** -m**, 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
2021-04-16 06:23:52 +00:00
respectively. Top, right, and bottom margins are ignored when ** -k** is used.
Negative margins are illegal.
Fully general ncvisual layer (#647)
This represents an essentially complete rewrite of ncvisual and associated code. It had two major goals:
Improve the ncvisual API based off lessons learned, pursuant to the upcoming API freeze. In particular, I wanted to:
decouple ncvisuals from ncplanes. It should be possible to render a ncvisual to multiple planes, with different scaling each time. It should be possible to create an ncvisual without a plane, etc.
normalize the various ways of constructing an ncvisual -- file, memory, plane, etc.
Support multiple blitters, from 7-bit ASCII to Sixel. This required writing the blitters in several cases, and they're not yet in their final implementations (but the API is fine)
I have not yet unified Plots and Visuals, and might not, given that the Plot code works fine. We could at this point implement Plots in terms of Visuals, though -- the blitter backend range has been unified. Sixel is not yet implemented, though it is listed.
There is a new POC tool, blitter. It renders its arguments using all possible blitter+scaling combinations. Another new POC, resize, displays its argument, then resizes it to the screen size and displays that, explicitly making use of ncvisual_resize() rather than a scaling parameter to ncvisual_render().
This also eliminates some memory leaks and bugs we were seeing in trunk, and brings in Sixel scaffolding.
The C++ wrapper will also need patching back up; I cut most of it down while wrestling with this crap, urk.
Closes #638, #562, and #622.
2020-05-29 01:16:58 +00:00
Scaling mode **stretch** resizes the object to match the target rendering
2021-03-12 23:13:19 +00:00
area exactly. Unless a blitter is specified with ** -b**, **stretch** will use
the highest-resolution non-pixel blitter available. **scale** 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. **none** uses the original
image size. Both **scale** and **none** aim for a 1:1 aspect ratio, and default
to **NCBLIT_2x1** at the cost of some potential resolution. The alternatives
**scalehi** and **hires** use the highest-resolution non-pixel blitter
available. Pixel blitting is never performed unless explicitly requested with
**-bpixel**.
2021-03-14 08:12:57 +00:00
Blitters can be selected at runtime by pressing '0' through '6'.
2021-03-12 23:13:19 +00:00
**NCBLIT_DEFAULT** corresponds to '0'. The various blitters are described in
2021-03-14 08:12:57 +00:00
**notcurses_visual(3)**. If a blitter cannot be used in the current environment,
the current blitter will be retained.
2021-03-12 23:13:19 +00:00
Multiframe media can be paused with space. Press space (or any other valid
control) to resume.
2020-06-05 15:51:05 +00:00
2020-01-14 20:50:16 +00:00
# NOTES
2020-02-12 01:46:39 +00:00
2021-02-09 23:46:21 +00:00
If you're looking for a fast, inline image viewer for the shell, try using
**ncplayer -k -t0 -q**.
2020-01-14 20:50:16 +00:00
Optimal display requires a terminal advertising the **rgb** terminfo(5)
capability, or that the environment variable **COLORTERM** is defined to
2020-02-12 01:46:39 +00:00
**24bit** (and that the terminal honors this variable), along with a
fixed-width font with good coverage of the Unicode Block Drawing Characters.
2020-01-14 20:50:16 +00:00
2021-02-15 00:23:51 +00:00
# BUGS
2021-04-14 22:59:23 +00:00
Direct mode is kinda fundamentally suboptimal for multiframe media, and
2021-04-16 06:23:52 +00:00
is not yet supported with ** -L** nor ** -d**. Top, right, and bottom
margins are ignored without warning when using direct mode.
2021-02-15 00:23:51 +00:00
2020-01-14 20:50:16 +00:00
# SEE ALSO
2020-02-12 01:46:39 +00:00
**notcurses(3)**,
2021-02-14 23:38:28 +00:00
**notcurses_direct(3)**,
2020-06-03 20:32:27 +00:00
**notcurses_visual(3)**,
2020-02-12 01:46:39 +00:00
**terminfo(5)**,
**unicode(7)**
