FreeBSD Manual Pages
SWAYIMGRC(5) Swayimg configuration SWAYIMGRC(5) NAME swayimgrc - configuration file for the Swayimg viewer SYNOPSIS The Swayimg configuration file is a text-based INI file used to over- ride 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 • /usr/local/etc/xdg/swayimg/config DESCRIPTION The structure of the INI file consists of key-value pairs for proper- ties 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 declara- tion 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 config- uration. 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 (de- fault); • 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 co- ordinates 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 de- fault (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 de- pending 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 down- scale; • bilinear: bilinear; • bicubic: bicubic with the Catmull-Rom spline; • mks13: Magic Kernel with the 2013 Sharp approximation (de- fault). 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 de- fault. 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 de- fault. 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 down- scale; • bilinear: bilinear; • bicubic: bicubic with the Catmull-Rom spline; • mks13: Magic Kernel with the 2013 Sharp approximation (de- fault). 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 op- tion 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 de- fault. 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,+file- size,+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 semi- colons. 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: xk- bcli 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/usr/local/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 [de- fault]; • 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 posi- tion. 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/usr/lo- cal/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 opera- tion. 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 lo- cally 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. swayimg 2026-01-13 SWAYIMGRC(5)
NAME | SYNOPSIS | LOCATION | DESCRIPTION | SECTIONS | Actions | EXAMPLES | SEE ALSO | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=swayimgrc&sektion=5&manpath=FreeBSD+Ports+15.0.quarterly>