SWAYIMGRC(5)

NAME
swayimgrc - configuration file for the Swayimg viewer

SYNOPSIS
The Swayimg configuration file is a text-based INI file used to override the default settings.

LOCATION
Swayimg searches for a config file in the following locations, in this order:
- $XDG_CONFIG_HOME/swayimg/config
- $HOME/.config/swayimg/config
- $XDG_CONFIG_DIRS/swayimg/config
- /etc/xdg/swayimg/config

DESCRIPTION
The structure of the INI file consists of key-value pairs for properties and sections that organize properties.

The basic element contained in the INI file is the key or property. Every key has a name and a value, delimited by an equals sign (=).

The name appears to the left of the equals sign. The value can contain any characters.

Keys are grouped into named sections. The section name appears on a line by itself, in square brackets ([ and ]). All keys after the section declaration are associated with that section.

The number sign (#) at the beginning of the line indicates a comment. Empty lines and comments are ignored.

Any option can be overridden using the --config argument in the command line, for instance: `swayimg --config="general.mode=gallery"`.

SECTIONS

  General
General configuration (for the whole application) is in section [general].

mode = [viewer|gallery]
    Mode used at startup, viewer by default.

position = [parent|X,Y]
    Initial window position (Sway only):
    parent: set position from parent (currently active) window (default);
    X,Y: absolute coordinates of the top left corner, e.g. 100,200.

size = [fullscreen|parent|image|W,H]
    Initial window size:
    fullscreen: use fullscreen mode;
    parent: set size from parent (currently active) window (Sway only, default);
    image: set size from the first loaded image;
    W,H: absolute size of the window in pixels.

decoration = [yes|no]
    Use window decoration (borders and title), no by default.

sigusr1 = ACTION
    Action to be performed when the SIGUSR1 signal is triggered, reload by default.

sigusr2 = ACTION
    Action to be performed when the SIGUSR2 signal is triggered, next_file by default.

app_id = NAME
    Application ID used as window class name, swayimg by default.

  Viewer
Configuration specific to the viewer mode is in section [viewer].

window = #COLOR
    Window background color in RGB or RGBA format, #00000000 by default.

transparency = [grid|#COLOR]
    Background for transparent images:
    grid: draw chessboard (default);
    #COLOR: solid color in RGB or RGBA, e.g "#10ff4280".

scale = MODE
    Default image scale, valid modes are:
    optimal: 100% or less to fit to window (default);
    width: fit image width to window width;
    height: fit image height to window height;
    fit: fit to window;
    fill: crop image to fill the window;
    real: real size (100%).

keep_zoom = [yes|no]
    Keep absolute zoom across images, no by default.

position = POSITION
    Initial image position on the window, valid modes are:
    top: move image to top and center by width;
    center: center by width and height (default);
    bottom: move to bottom and center by width;
    left: move to left and center by height;
    right: move to right and center by height;
    topleft: move to top and left;
    topright: move to top and right;
    bottomleft: move to bottom and left;
    bottomright: move to bottom and right;
    free: like center, but freely movable (not fixed).

antialiasing = METHOD
    Anti-aliasing method when scaling images, valid options are:
    none: nearest-neighbor, or no anti-aliasing;
    box: nearest-neighbor on upscale, average in a box on downscale;
    bilinear: bilinear;
    bicubic: bicubic with the Catmull-Rom spline;
    mks13: Magic Kernel with the 2013 Sharp approximation (default).
    In general, the methods improve in quality and decrease in performance from top to bottom.

slideshow = [yes|no]
    Run slideshow at startup, no by default.

slideshow_time = SECONDS
    Slideshow image duration in seconds, 3 by default.

history = SIZE
    Number of previously viewed images to store in cache, 1 by default.

preload = SIZE
    Number of images to preload in a separate thread, 1 by default.

  Gallery
Configuration specific to the gallery mode is in section [gallery].

size = PIXELS
    Height and width of each thumbnail in pixels, 200 by default.

cache = SIZE
    Max number of invisible thumbnails stored in memory cache, 100 by default.

preload = [yes|no]
    Load not only visible but also adjacent thumbnails, no by default. The cache parameter limits the number of preloaded thumbnails.

pstore = [yes|no]
    Enable/disable storing thumbnails in persistent storage, no by default.

fill = [yes|no]
    Fill the entire tile with thumbnail, yes by default.

antialiasing = METHOD
    Anti-aliasing method when scaling thumbnails, valid options are:
    none: nearest-neighbor, or no anti-aliasing;
    box: nearest-neighbor on upscale, average in a box on downscale;
    bilinear: bilinear;
    bicubic: bicubic with the Catmull-Rom spline;
    mks13: Magic Kernel with the 2013 Sharp approximation (default).
    In general, the methods improve in quality and decrease in performance from top to bottom.

window = #COLOR
    Background color of the window, #00000000 by default.

background = #COLOR
    Background color of non-selected tiles, #202020ff by default.

select = #COLOR
    Background color of the selected tile, #404040ff by default.

border = #COLOR
    Border color of the selected tile, #000000ff by default.

shadow = #COLOR
    Shadow color of the selected tile, #000000ff by default.

  Image list
Configuration of the image list is in section [list].

order = ORDER
    Order of the image list:
    none: unsorted, order is system-dependent;
    alpha: sorted alphabetically (default);
    numeric: sorted numerically;
    mtime: sorted by file modification time;
    size: sorted by file size;
    random: randomize list.

reverse = [yes|no]
    Reverse sort order, no by default.

loop = [yes|no]
    Looping file list mode, yes by default.

recursive = [yes|no]
    Read directories recursively, no by default.

all = [yes|no]
    Add all files from the same directory as the first file. This option is ignored
    if more than one input file is specified. Default value is no.

fsmon = [yes|no]
    Enable file system monitoring for adding new images to the list, yes by
    default.

  Font
Font configuration is in section [font].

name = NAME
    Font name, monospace by default.

size = SIZE
    Font size (in pt), 14 by default.

color = #COLOR
    Text color, #ccccccff by default.

shadow = #COLOR
    Text shadow color, #000000d0 by default.
    To disable shadow use fully transparent color #00000000.

background = #COLOR
    Text background color, #00000000 (none) by default.

  Text info: common configuration
Section [info] describes how to display image metadata (file name, size, EXIF, etc.) in general.

show = [yes|no]
    Enable or disable info text at startup, yes by default.

info_timeout = SECONDS
    Timeout of image information displayed on the screen, 0 to always show, 5 by default.

status_timeout = SECONDS
    Timeout of the status message displayed on the screen, 3 by default.

  Text info: viewer
Section [info.viewer] describes what image metadata to display in viewer mode.
Metadata may be displayed in any corner of the screen. This section defines
the following keys, each of which describes the metadata to appear in that location:

top_left = LIST
    Default is +name,+format,+filesize,+imagesize,+exif.

top_right = LIST
    Default is index.

bottom_left = LIST
    Default is scale,frame.

bottom_right = LIST
    Default is status.

LIST may contain any number of the following fields, separated by commas.
A plus sign preceding a field name adds the field title to the display.

name
    File name of the currently viewed/selected image.

dir Parent directory name of the currently viewed/selected image.

path
    Absolute path or special source string of the currently viewed/selected image.

filesize
    File size in human-readable format.

format
    Brief image format description.

imagesize
    Size of the image (or its current frame) in pixels.

exif
    List of EXIF data.

frame
    Current and total number of frames.

index
    Current and total index of image in the image list.

scale
    Current image scale in percent.

status
    Status message.

none
    Empty field (ignored).

  Text info: gallery
Section [info.gallery] describes what image metadata to display in gallery mode.
It follows the same format as [info.viewer], with the following keys:

top_left = LIST
    Default is none.

top_right = LIST
    Default is none.

bottom_left = LIST
    Default is none.

bottom_right = LIST
    Default is name,status.

  Key bindings
The key bindings are described in sections [keys.viewer] and [keys.gallery]. Each line associates a key with a list of actions and optional parameters. Actions are separated by semicolons. One or more key modifiers (Ctrl, Alt, Shift) can be specified in the key name. The key name can be obtained with the xkbcli tool: `xkbcli interactive-wayland`.

Predefined names for mouse scroll:

ScrollUp: Mouse wheel up;

ScrollDown: Mouse wheel down;

ScrollLeft: Mouse scroll left;

ScrollRight: Mouse scroll right.

  Viewer mode actions

none: can be used to remove a built-in action;

help: show/hide help;

first_file: jump to the first file;

last_file: jump to the last file;

prev_dir: jump to previous directory;

next_dir: jump to next directory;

prev_file: jump to previous file;

next_file: jump to next file;

rand_file: jump to random file;

prev_frame: show previous frame;

next_frame: show next frame;

skip_file: skip the current file (remove from the image list);

animation: start/stop animation;

slideshow: start/stop slideshow;

fullscreen: toggle full-screen mode;

mode [MODE]: switch between viewer and gallery;

step_left [PERCENT]: move viewport left, default is 10%;

step_right [PERCENT]: move viewport right, default is 10%;

step_up [PERCENT]: move viewport up, default is 10%;

step_down [PERCENT]: move viewport down, default is 10%;

zoom [SCALE]: zoom in/out/fix, SCALE is one of viewer.scale modes, or percent, e.g. +10;

scale [SCALE]: set default/global scale, SCALE is one of viewer.scale modes, cycles through available modes by default;

keep_zoom: toggle zoom keeping mode;

rotate_left: rotate image anticlockwise;

rotate_right: rotate image clockwise;

flip_vertical: flip image vertically;

flip_horizontal: flip image horizontally;

reload: reset cache and reload current image;

antialiasing [MODE]: set anti-aliasing mode or cycle through them (next/prev or mode name);

info [MODE]: set info mode or cycle through them (off/viewer/gallery);

exec COMMAND: execute an external command, use % to substitute the path to the current image, %% to escape %;

export FILE: export currently displayed image to PNG file;

status TEXT: print message in the status field;

exit: exit the application.

  Gallery mode actions

none: can be used to remove a built-in action;

help: show/hide help;

first_file: jump to the first file;

last_file: jump to the last file;

prev_file: select previous file;

next_file: select next file;

step_left: select previous image;

step_right: select next image;

step_up: select image above;

step_down: select image below;

page_up: scroll page up;

page_down: scroll page down;

skip_file: skip the current file (remove from the image list);

fullscreen: toggle full-screen mode;

mode: switch between viewer and gallery;

reload: reset cache and reload current image;

antialiasing [MODE]: set anti-aliasing mode or cycle through them (next/prev or mode name);

info [MODE]: set info mode or cycle through them (off/viewer/gallery);

exec COMMAND: execute an external command, use % to substitute the path to the current image, %% to escape %;

status TEXT: print message in the status field;

exit: exit the application.

EXAMPLES
    # comment
    [list]
    order = random
    [font]
    size = 16
    [keys]
    Ctrl+Alt+e = exec echo "%" > mylist.txt

See `/usr/share/swayimg/swayimgrc` for full example.

SEE ALSO
swayimg(1)

BUGS
For suggestions, comments, bug reports, etc. visit the project homepage (https://github.com/artemsen/swayimg).