Live previews

Video preview with nnn

Live previews

A live preview is a window that renders or shows information on the hovered entry. As the cursor moves, the live preview window will automatically update.

There are two ways to enable live previews in nnn:

1. using a previewer plugin,
2. using a custom wrapper/previewer script.

Both use the path in NNN_FIFO to get hover updates.

Previewer plugins

Set up NNN_FIFO

Depends on how many simultaneous nnn instances you need:

1. Single instance: export a global FIFO path in, e.g., .profile:

   export NNN_FIFO=/tmp/nnn.fifo

2. Multiple instances: use the option -a to create a new FIFO path for each instance.

Plugin usage

Follow the instructions in the plugin documentation for installation and general plugin configuration.

There are 2 previewer plugins for nnn, using various mechanisms to display the preview window:

• preview-tabbed: the preview window is a tabbed X window, files are viewed using Xembed capable programs (mpv for audio/video, sxiv for images, zathura for PDF, xterm/urxvt/st + nuke plugin text preview for other files)
• preview-tui: the preview window is either a tmux pane, a new terminal window or a kitty pane (needs kitty's allow_remote_control option turned on), and files are previewed using tools like tree, less, file, mediainfo, kitty's icat, ueberzug etc. On WSL it will use QuickLook to preview files. It can also use ranger's scope.sh or pistol. Feel free to submit a pull-request for any previewer you feel is missing.

To run a previewer (or any plugin in general) when you start nnn, use the option -P

Notes:

1. nnn does not watch the hovered file and update the path if it's modified while under preview. Press Esc or click on the entry to update the preview without changing the hovered entry.
2. To close the preview-tui preview windows run the plugin again or press ^C on the preview window.

Custom script configuration example

There are two aspects to creating a live preview:

1. A preview command
2. A setup command

Preview command example

#!/usr/bin/env sh
# #############################################################################
# File: preview_cmd.sh
# Description: Minimal example to preview files and directories
#              No external dependencies
#              Can be easily extended
#              Automatically exits when the NNN_FIFO closes
#              Prints a `tree` if directory or `head` if it's a file
#
# Shell: POSIX compliant
# Author: Todd Yamakawa
#
# ToDo:
#   1. Add support for more types of files
#         e.g. binary files, we shouldn't try to `head` those
# #############################################################################

# Check FIFO
NNN_FIFO=${NNN_FIFO:-$1}
if [ ! -r "$NNN_FIFO" ]; then
    echo "Unable to open \$NNN_FIFO='$NNN_FIFO'" | less
    exit 2
fi

# Read selection from $NNN_FIFO
while read -r selection; do
    clear
    lines=$(($(tput lines)-1))
    cols=$(tput cols)

    # Print directory tree
    if [ -d "$selection" ]; then
        cd "$selection" || continue
        tree | head -n $lines | cut -c 1-"$cols"
        continue
    fi

    # Print file head
    if [ -f "$selection" ]; then
        head -n $lines "$selection" | cut -c 1-"$cols"
        continue
    fi

    # Something went wrong
    echo "Unknown type: '$selection'"
done < "$NNN_FIFO"

Setup command example

To create your own setup command, you need the following steps:

1. Create a NNN_FIFO
2. Run your preview command in the background
3. Run nnn
4. Delete your NNN_FIFO

Here is am example bash/zsh function. To use this example, you will need to set the preview command. For the preview window:

• It uses tmux split if you're currently running in a tmux environment
  • tmux 3.0 is required for setting environment variables in a new pane
• Otherwise it uses an xterm window

nnn-preview ()
{
    # Block nesting of nnn in subshells
    if [ -n "$NNNLVL" ] && [ "${NNNLVL:-0}" -ge 1 ]; then
        echo "nnn is already running"
        return
    fi

    # The default behaviour is to cd on quit (nnn checks if NNN_TMPFILE is set)
    # If NNN_TMPFILE is set to a custom path, it must be exported for nnn to see.
    # To cd on quit only on ^G, remove the "export" and set NNN_TMPFILE *exactly* as this:
    #     NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"
    export NNN_TMPFILE="${XDG_CONFIG_HOME:-$HOME/.config}/nnn/.lastd"

    # This will create a fifo where all nnn selections will be written to
    NNN_FIFO="$(mktemp --suffix=-nnn -u)"
    export NNN_FIFO
    (umask 077; mkfifo "$NNN_FIFO")

    # Preview command
    preview_cmd="/path/to/preview_cmd.sh"

    # Use `tmux` split as preview
    if [ -e "${TMUX%%,*}" ]; then
        tmux split-window -e "NNN_FIFO=$NNN_FIFO" -dh "$preview_cmd"

    # Use `xterm` as a preview window
    elif (which xterm &> /dev/null); then
        xterm -e "$preview_cmd" &

    # Unable to find a program to use as a preview window
    else
        echo "unable to open preview, please install tmux or xterm"
    fi

    nnn "$@"

    rm -f "$NNN_FIFO"
}