Skip to content
Overview
Configuration Reference
Idle & DPMS

Idle & DPMS

SamWM manages screen idle state and DPMS (Display Power Management Signaling) for automatic screen blanking and power saving.

Configuration 

samwm.general({
    idle = {
        -- Seconds before idle action triggers
        timeout = 300,

        -- Action on idle: off, blank, lock, suspend
        action = "blank",

        -- Enable DPMS (screen power off)
        dpms = true,

        -- Seconds before DPMS power off
        dpms_timeout = 600,
    }
})

Idle Timeout

When the user is idle for the specified time, SamWM executes the idle action:

samwm.general({
    idle = {
        timeout = 300, -- 5 minutes
        action = "off", -- Turn screen off
    }
})

Available Actions

Action Description
off Turn screen off via DPMS
blank Show blank screen (keep backlight)
lock Lock the session
suspend Suspend to RAM
hibernate Hibernate to disk
none No action

DPMS

DPMS allows controlling screen power state. When enabled, screens will turn off after the DPMS timeout.

samwm.general({
    idle = {
        dpms = true,
        dpms_timeout = 600, -- 10 minutes of idle
        dpms_standby = 300, -- Standby after 5 minutes
        dpms_suspend = 600, -- Suspend after 10 minutes
        dpms_off = 900, -- Off after 15 minutes
    }
})

Idle Inhibitor

Some applications (like video players) should prevent screen blanking. SamWM supports the Wayland idle inhibitor protocol:

  • Applications can request idle inhibition
  • While inhibited, the idle timer is paused
  • Inhibition is automatically removed when the app unmaps

Keybindings for Idle 

-- Manually trigger idle action
samwm.bind("SUPER", "L", "exec swayidle", "Lock screen")

-- Toggle DPMS off immediately
samwm.bind("SUPER", "F4", "dpms off", "Turn screen off")

-- Turn screen on
samwm.bind("SUPER", "F5", "dpms on", "Turn screen on")

Idle Actions 

-- Lock screen
samwm.bind("SUPER", "L", "lock", "Lock screen")

-- Suspend
samwm.bind("SUPER+SHIFT", "S", "suspend", "Suspend system")

-- Turn off monitors
samwm.bind("SUPER", "F4", "dpms off", "Turn monitors off")

-- Reset idle timer (wake screen)
samwm.bind("SUPER", "F5", "dpms on", "Turn monitors on")

Lua API

Get Idle Status 

local status = samwm.get_idle()
print("Idle time:", status.idle_time, "seconds")
print("Locked:", status.locked)

Reset Idle Timer 

samwm.reset_idle()
-- Screen will wake if blanked

Set Idle Timeout 

samwm.set_idle_timeout(600) -- 10 minutes

Control DPMS 

samwm.dpms("off")  -- Turn off
samwm.dpms("on")   -- Turn on
samwm.dpms("toggle") -- Toggle

Waybar Integration 

"custom/idle inhibitor": {
    "exec": "echo '{\"text\":\"\"}'",
    "format": "{}",
    "interval": 30,
    "signal": 8
}

External Tools

SamWM can integrate with external idle tools:

-- Use swayidle for more advanced idle management
samwm.general({
    startup_commands = {
        "swayidle -t 300 -l 'swaylock -f' &"
    }
})

Event Hooks 

-- On idle triggered
samwm.on("idle", function()
    print("System is idle")
end)

-- On wake from idle
samwm.on("wake", function()
    print("User is active again")
end)

-- Before idle (for notifications)
samwm.on("pre_idle", function(seconds)
    print("Will idle in", seconds, "seconds")
end)
Hot ReloadKeyboard Layout