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 number sign (#) at the beginning of the line indicates a comment. Empty lines and comments are ignored.

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. All keys after the section declaration are associated with that section.

Special directive include allows one to load another config file. The directive must contain the path or name of the file to load the configuration.

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 entire application: [general].

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

size = fullscreen|image|W,H
    Initial window size:
    •   fullscreen: use full screen mode;
    •   image: set size from the first frame of the first image;
    •   W,H: absolute size of the window in pixels, default is 1280,720.

position = auto|X,Y
    Only Sway and Hyprland: Initial window position:
    •   auto: let the window manager control the window position (default);
    •   X,Y: absolute coordinates of the top left corner, e.g. 100,200.

overlay = yes|no
    Only Sway and Hyprland: Create a floating window with the same coordinates and size as the currently focused window. This options overrides position and size parameters. Default value is no.

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.

  DRM mode settings

Configuration used to initialize DRM mode: [drm].

path = auto|PATH
    Path to the DRM device, e.g. /dev/dri/card1, auto by default (use first available).

connector = auto|NAME
    Connector name e.g. DP-1, auto by default (use first available).

mode = auto|MODE
    Display resolution and frequency, e.g. 1920x1080@60, auto by default (use preferred or first available).

  Viewer

Configuration specific to the viewer mode: [viewer].

window = auto|extend|mirror|#COLOR
    Window background:
    •   auto: fill the window background in extend or mirror mode depending on the image aspect ratio;
    •   extend: fill window with the current image and blur it;
    •   mirror: fill window with the mirrored current image and blur it;
    •   #COLOR: solid color in RGB or RGBA, #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
    Initial image scale:
    •   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: keep the same scale as for previously viewed image.

position = POSITION
    Initial image position on the window:
    •   center: center of the window (default);
    •   top: top and center horizontally;
    •   bottom: bottom and center horizontally;
    •   left: left and center vertically;
    •   right: right and center vertically;
    •   top_left: upper left corner of the window;
    •   top_right: upper right corner of the window;
    •   bottom_left: lower left corner of the window;
    •   bottom_right: lower right corner of the window;
    •   free: like center, but freely movable (not fixed).

antialiasing = METHOD
    Anti-aliasing method when scaling images. In general, the methods improve in quality and decrease in performance from top to bottom:
    •   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).

loop = yes|no
    Loop image list: jump to first image when end of list is reached, yes 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.

  Slide show

Configuration specific to the slide show mode: [slideshow].

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

window
    Same format as for viewer.window.

transparency
    Same format as for viewer.transparency.

scale
    Same format as for viewer.scale.

position
    Same format as for viewer.position.

antialiasing
    Same format as for viewer.antialiasing.

  Gallery

Configuration specific to the gallery mode: [gallery].

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

selected_scale = FLOAT
    Scale of the selected tile, 1.15 by default.

aspect = fit|fill|keep
    Thumbnail aspect ratio, fill by default.
    •   fit: Fit image into a square thumbnail, maintaining its aspect ratio;
    •   fill: Fill square thumbnail with the image, cropping its larger dimension;
    •   keep: Adjust thumbnail size to the aspect ratio of the image.

padding = PIXELS
    Padding between thumbnails in pixels, 5 by default.

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

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

border_color = #COLOR
    Border color of the selected tile, #aaaaaaff by default.

border_width = PIXELS
    Border width of the selected tile, 5 pixels by default.

window = #COLOR
    Window background color in RGB or RGBA format, #00000000 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. If enabled, thumbnails will be stored in XDG_CACHE_HOME/swayimg.

antialiasing = METHOD
    Anti-aliasing method when scaling images. In general, the methods improve in quality and decrease in performance from top to bottom:
    •   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).

  Image list

Configuration of the image list: [list].

order = ORDER
    Order of the image list:
    •   none: unsorted;
    •   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.

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 to automatically update the image list, yes by default.

  Font

Font configuration: [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 (fully transparent) by default.

  Text info: general configuration

General configuration of the displayed text layer: [info].

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

padding = PADDING
    Text padding from window edges (in px), 10 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 mode

Layout of fields for displaying text info in viewer mode: [info.viewer]. The layout describes what metadata should be displayed in each corner of the window. The list can contain any number of fields separated by commas. A plus sign preceding a field name adds the field title to the display.

top_left = LIST
    Top left corner of the window. Default is +name,+format,+filesize,+imagesize,+exif.

top_right = LIST
    Top right corner of the window. Default is index.

bottom_left = LIST
    Bottom left corner of the window. Default is scale,frame.

bottom_right = LIST
    Bottom right corner of the window. Default is status.

Available fields:
•   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: slide show mode

Layout of fields for displaying text info in slide show mode: [info.slideshow]. The format is the same as [info.viewer].

  Text info: gallery mode

Layout of fields for displaying text info in gallery mode: [info.gallery]. The format is the same as [info.viewer].

  Key bindings

Key bindings configurations are stored in sections [keys.viewer], [keys.slideshow] 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 buttons/scroll:
•   MouseLeft: Left button;
•   MouseRight: Right button;
•   MouseMiddle: Middle button;
•   MouseSide: Side button;
•   MouseExtra: Extra button;
•   ScrollUp: Mouse wheel up;
•   ScrollDown: Mouse wheel down;
•   ScrollLeft: Mouse scroll left;
•   ScrollRight: Mouse scroll right.

Actions

none
    Dummy, does nothing. Can be used to remove default key bindings.

help
    Show/hide help.

first_file
    Go to the first file.

last_file
    Go to the last file.

prev_file
    Go to previous file.

next_file
    Go to next file.

prev_dir
    Viewer/Slideshow modes only. Go to previous directory.

next_dir
    Viewer/Slideshow modes only. Go to next directory.

rand_file
    Viewer/Slideshow modes only. Go to random file.

step_left
    Gallery mode only. Select previous image.

step_right
    Gallery mode only. Select next image.

step_up
    Gallery mode only. Select image above.

step_down
    Gallery mode only. Select image below.

page_up
    Gallery mode only. Scroll page up.

page_down
    Gallery mode only. Scroll page down.

skip_file
    Viewer/Gallery modes only. Skip the current file (remove it from the image list).

prev_frame
    Viewer mode only. Show previous frame.

next_frame
    Viewer mode only. Show next frame.

animation
    Viewer mode only. Stop/continue animation.

fullscreen
    Toggle full-screen mode.

mode [viewer|slideshow|gallery]
    Switch between modes. Empty value to switch to previous mode.

step_left [PERCENT]
    Viewer mode only. Move viewport left, default is 10%.

step_right [PERCENT]
    Viewer mode only. Move viewport right, default is 10%.

step_up [PERCENT]
    Viewer mode only. Move viewport up, default is 10%;

step_down [PERCENT]
    Viewer mode only. Move viewport down, default is 10%;

zoom [SCALE [POSITION]]
    Viewer mode only. Manage scaling, SCALE is:
    •   one of the viewer.scale modes (fit/fill/etc);
    •   percentage number with + or - sign (e.g. +10) to zoom in or out;
    •   absolute value in percentage to set the scale, e.g. 200;
    •   empty value to switch to the next available scaling mode.

    POSITION is one of:
    •   center to zoom into and out of the center of the viewport [default];
    •   mouse to zoom into and out of the mouse cursor position.

position [POSITION]
    Viewer mode only. Change image position; POSITION can be one of the viewer.position directions, or empty to switch to the next position.

rotate_left
    Viewer mode only. Rotate image anticlockwise.

rotate_right
    Viewer mode only. Rotate image clockwise.

flip_vertical
    Viewer mode only. Flip image vertically.

flip_horizontal
    Viewer mode only. Flip image horizontally.

thumb SIZE
    Gallery mode only. Resize thumbnails, SIZE is:
    •   delta in pixels with + or - sign (e.g. +10);
    •   absolute size in pixels, e.g. 200.

reload
    Viewer/Gallery modes only. Reset cache and reload current image.

antialiasing [MODE]
    Viewer/Gallery modes only. Set anti-aliasing mode or switch if on/off, MODE is:
    •   one of the viewer.antialiasing modes (none/mks13/etc);
    •   empty value to toggle AA on/off.

info [MODE]
    Switch or cycle text info modes.

    With no MODE, the mode cycles through: off/viewer/slideshow/gallery.

    If MODE is a single mode name (e.g. viewer), switch to that mode. If MODE is a comma-separated list (e.g. viewer,off), cycle through the listed modes. Spaces around commas are ignored.

    Each entry must be either off or the name of a configured scheme.

exec COMMAND
    Execute an external command, use % to substitute the full path to the current image, %% to escape %. Swayimg waits for child processes to complete, to "detach" the child process from Swayimg, call any another launcher, for example:
    •   Sway: `swaymsg exec ...`;
    •   Hyprland: `hyprctl dispatch exec ...`;
    •   Niri: `niri msg action spawn ...`.

drag
    Mouse buttons in viewer mode only. Set the button for drag operation.

export FILE
    Viewer mode only. Export currently displayed image to PNG file.

pause
    Slideshow mode only. Pause/continue slideshow.

status TEXT
    Display text in status field.

exit
    Exit the application.

EXAMPLES
Sample file is available on the project repository: https://github.com/artemsen/swayimg/blob/master/extra/swayimgrc or locally after installation: /usr/share/swayimg/swayimgrc.

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

SEE ALSO
swayimg(1)

BUGS

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