--- name: "swayimgrc" section: "5" platform: "linux" package: "swayimg" version: "3.8-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/swayimgrc" --- # swayimgrc(5) configuration file for the Swayimg viewer ## 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 The general configuration is stored in the section **\[general\]**. - **mode** = *\[viewer\|gallery\]* Mode used at startup, *viewer* by default. - **position** = *\[parent\|X,Y\]* Set initial position of the window (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\]* Set initial size of the window: ``` 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* Set the action to be performed when the SIGUSR1 signal is triggered. Default value is *reload*. - **sigusr2** = *ACTION* Set the action to be performed when the SIGUSR2 signal is triggered. Default value is *next\_file*. - **app\_id** = *NAME* Application ID used as window class name. ### Viewer Configuration is defined in the **\[viewer\]** section. - **window** = *#COLOR* Window background color in RGB or RGBA format, default is *#00000000*. - **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, 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. ``` - **fixed** = *\[yes\|no\]* Fix position of the image on the window surface, *yes* by default. - **antialiasing** = *METHOD* Scale method to use when anti-aliasing is enabled, valid choices are: ``` nearest: nearest-neighbor, equivalent to antialiasing = no; 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* Set slideshow image duration in seconds, default is *3*. - **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 is defined in the **\[gallery\]** section. - **size** = *PIXELS* Size of the thumbnail in pixels, *200* by default. - **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. - **cache** = *SIZE* Max number of thumbnails in cache, *0* for unlimited, *100* by default. - **antialiasing** = *METHOD* Scale method to use when anti-aliasing is enabled, valid choices are: ``` nearest: nearest-neighbor, equivalent to antialiasing = no; 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, default is *#00000000*. - **background** = *#COLOR* Background color of the tile, default is *#202020ff*. - **border** = *#COLOR* Border color of the selected tile, default is *#000000ff*. - **shadow** = *#COLOR* Shadow color of the selected tile, default is *#000000ff*. ### Image list The image list configuration is stored in the section **\[list\]**. - **order** = *ORDER* Set order of the image list: ``` none: unsorted, order is system depended; alpha: sorted alphabetically (default); reverse: reversed alphabetically; random: randomize list. ``` - **loop** = *\[yes\|no\]* Looping file list mode, *yes* by default. - **recursive** = *\[yes\|no\]* Read directories recursively, *no* by default. - **all** = *\[yes\|no\]* Open all files in the directory of the specified file, *no* by default. ### Font The font configuration is stored in the section **\[font\]**. - **name** = *NAME* Set the font name used for text, default is *monospace*. - **size** = *SIZE* Set the font size (in pt), default is *14*. - **color** = *#COLOR* Set text color in RGBA format, default is *#ccccccff*. - **background** = *#COLOR* Text background color, default is *#00000000* (none). - **shadow** = *#COLOR* Draw text shadow with specified color, default is *#000000d0*. To disable shadow use fully transparent color *#00000000*. ### Text info: common configuration The section **\[info\]** describes how to display image meta data (file name, size, EXIF etc). - **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, default is *5*. - **status\_timeout** = *SECONDS* Timeout of the status message displayed on the screen, default is *3*. ### Text info: viewer The section **\[info.viewer\]** describes how to display image meta data (file name, size, EXIF etc) in viewer mode. Each key/value configures a set of fields and their format. - **top\_left** = *LIST* Set the display scheme for the upper left corner of the window. - **top\_right** = *LIST* Set the display scheme for the upper right corner of the window. - **bottom\_left** = *LIST* Set the display scheme for the lower left corner of the window. - **bottom\_right** = *LIST* Set the display scheme for the lower right corner of the window. *LIST* can contain any number of fields separated by commas. Plus at the beginning of a field name adds the field title to the display. Available fields: - *name* File name of the currently viewed/selected image. - *dir* Parent directory name 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 The section **\[info.gallery\]** describes how to display image meta data (file name, size, EXIF etc) in gallery mode, same format as for viewer mode. ### 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 for removing 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**: switch 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**: switch antialiasing mode; - **info** *\[MODE\]*: switch text info mode or set specified one (*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. ### Gallery mode actions - **none**: can be used for removing 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**: switch full screen mode; - **mode**: switch between viewer and gallery; - **reload**: reset cache and reload current image; - **antialiasing**: switch antialiasing mode; - **info** *\[MODE\]*: switch text info mode or set specified one (*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)](/swayimg/1.md) ## BUGS For suggestions, comments, bug reports etc. visit the project homepage ⟨https://github.com/artemsen/swayimg⟩.