swayimg Documentation

Swayimg is available in various Linux distributions.

• Arch Linux: Install from the extra repository or via the swayimg-git package in the AUR.
• Other Distros: Check the Repology page for availability on your specific distribution.

To perform actions on a subset of images that have been marked, use swayimg.gallery.on_key to listen for a specific key combination (e.g., Ctrl-p). Retrieve the full list of entries using swayimg.imagelist.get() and iterate through them, checking the mark property of each entry.

swayimg.gallery.on_key("Ctrl-p", function()
  local entries = swayimg.imagelist.get()
  for _, entry in ipairs(entries) do
    if entry.mark then
        print(entry.path)
    end
  end
end)

To display custom information in the window title (such as the current image path) while in gallery mode, use the swayimg.gallery.on_image_change callback combined with swayimg.set_title().

swayimg.gallery.on_image_change(function()
  local image = swayimg.gallery.get_image()
  if image then
    swayimg.set_title("Gallery: "..image.path)
  end
end)

Swayimg does not provide a native double-click event, but you can simulate one using swayimg.viewer.on_mouse and swayimg.defer. By incrementing a counter on every click and using swayimg.defer to check the counter after a short delay, you can distinguish between single and double clicks.

local double_click_delay = 0.3 -- max 0.3 sec between clicks
local click_counter = 0

swayimg.viewer.on_mouse("MouseLeft", function()
  click_counter = click_counter + 1
  swayimg.defer(double_click_delay, function()
    if click_counter > 1 then
      print("Double click")
    else
      print("Single click")
    end
    click_counter = 0
  end)
end)

Swayimg is highly customizable using Lua scripts. By default, it searches for an init.lua file in the following locations:

• $XDG_CONFIG_HOME/swayimg/init.lua
• $HOME/.config/swayimg/init.lua
• $XDG_CONFIG_DIRS/swayimg/init.lua
• /etc/xdg/swayimg/init.lua

To use a specific configuration file or execute a script after loading the config, use the following CLI flags:

• -c, --config=_FILE_: Load a specific Lua file.
• -e, --execute=_LUA_: Execute a specific Lua script after the configuration is loaded.

swayimg -c my_custom_config.lua

You can automatically resize the swayimg window to match the dimensions of the currently loaded image by using the swayimg.viewer.on_image_change callback. To prevent scaling issues when the window is resized, use swayimg.viewer.set_fix_scale("fit") within the swayimg.on_window_resize callback.

swayimg.viewer.on_image_change(function()
  local image = swayimg.viewer.get_image()
  if image then
    swayimg.set_window_size(image.width, image.height)
  end
end)
swayimg.on_window_resize(function()
  swayimg.viewer.set_fix_scale("fit")
end)

You can use swayimg to view images via several input methods:

• Files/Directories: Pass one or more files or directories as arguments. If no arguments are provided, it reads all files in the current directory.
• Stdin: Use - as a filename to read image data from standard input.
• External Commands: Use the exec:// prefix to treat the output of an external command as image data.

Examples:

# View specific files
swayimg photo.jpg logo.png

# View image from a pipe
wget -qO- https://www.kernel.org/theme/images/logos/tux.png | swayimg -

# View images from external commands
swayimg "exec://wget -qO- https://www.kernel.org/theme/images/logos/tux.png" \
        "exec://curl -so- https://www.kernel.org/theme/images/logos/tux.png"

Swayimg uses a Lua script for configuration. The program searches for the configuration file in the following locations, in order of priority:

1. $XDG_CONFIG_HOME/swayimg/init.lua
2. $HOME/.config/swayimg/init.lua
3. $XDG_CONFIG_DIRS/swayimg/init.lua
4. /etc/xdg/swayimg/init.lua

After installation, you can use /usr/share/swayimg/swayimg.lua as a source file for your LSP server to get autocompletion and descriptions of the available Lua bindings.

-- Example init.lua
swayimg.text.size = 32
swayimg.text.color = 0xffff0000

swayimg.viewer.default_scale = "fill"

swayimg.gallery.on_key("Delete", function()
  local image = swayimg.gallery.get_image()
  os.remove(image.path)
end)

You can implement file deletion by binding a key (e.g., Delete) using swayimg.viewer.on_key. Inside the callback, retrieve the current image via swayimg.viewer.get_image(), use a system command like os.remove to delete the file, and optionally update the UI status message using swayimg.text.set_status().

swayimg.viewer.on_key("Delete", function()
  local image = swayimg.viewer.get_image()
  if image then
    os.remove(image.path)
    swayimg.text.set_status("File "..image.path.." removed")
  end
end)

Swayimg uses the Meson build system. To build and install from a source tree, follow these steps:

1. Set up the build directory.
2. Compile the project.
3. Install the binaries.

Ensure you have the necessary dependencies (such as libjpeg, libpng, libwebp, etc.) installed on your system before building.

meson setup my_build_dir
meson compile -C my_build_dir
meson install -C my_build_dir

You can configure how the slideshow behaves automatically using the following swayimg.slideshow fields:

• swayimg.slideshow.timeout: A number representing the timeout in seconds before the next image is opened.
• swayimg.slideshow.autocenter: A boolean (write-only) to enable automatic image centering.
• swayimg.slideshow.loop: A boolean (write-only) to enable image list loop mode.
• swayimg.slideshow.animation: A boolean used to stop/resume and get animation status.

swayimg.slideshow.timeout = 5
swayimg.slideshow.loop = true