Config

Protocol Documentation

Table of Contents

• hyprpanel/config/v1/config.proto

  • Config

  • Config.Audio

  • Config.DBUS

  • Config.DBUS.Brightness

  • Config.DBUS.Notifications

  • Config.DBUS.Power

  • Config.DBUS.Shortcuts

  • Config.DBUS.Systray

  • Panel

  • Edge

  • LogLevel

• hyprpanel/module/v1/module.proto

  • Audio

  • Clock

  • Hud

  • Module

  • Notifications

  • Pager

  • Power

  • Session

  • Spacer

  • Systray

  • SystrayModule

  • Taskbar

  • Position

  • Systray.Status

• Scalar Value Types

Top

hyprpanel/config/v1/config.proto

Config

Field	Type	Label	Description
log_level	LogLevel		specifies the maximum log level for output.
log_subprocesses_to_journal	bool		send processes spawned by e.g. taskbar launchers to the systemd journal via sytstemd-cat.
dbus	Config.DBUS		dbus configuration section.
audio	Config.Audio		audio configuration section.
panels	Panel	repeated	list of panels to display.

Config.Audio

Field	Type	Label	Description
enabled	bool		if false, no Audio functionality is available.
volume_step_percent	uint32		percentage that volume should change on each adjustment.
volume_exceed_maximum	bool		allow increasing volume above 100%.
hud_notifications	bool		display HUD notifications on volume change (requires at least one HUD module).

Config.DBUS

Field	Type	Label	Description
enabled	bool		if false, no DBUS functionality is available.
connect_timeout	google.protobuf.Duration		specifies the maximum time we will attempt to connect to the bus before failing (format: "20s").
connect_interval	google.protobuf.Duration		specifies the interval that we will attempt to connect to the session bus on startup (format: "0.200s").
notifications	Config.DBUS.Notifications		notifications configuration.
systray	Config.DBUS.Systray		systray configuration.
shortcuts	Config.DBUS.Shortcuts		shortcuts configuration.
brightness	Config.DBUS.Brightness		brightness configuration.
power	Config.DBUS.Power		power configuration.

Config.DBUS.Brightness

Field	Type	Label	Description
enabled	bool		enables brightness control functionality.
adjust_step_percent	uint32		percentage that brightness should change on each adjustment.
min_brightness	uint32		minimum brightness value.
enable_logind	bool		set brightness via systemd-logind DBUS interface instead of direct sysfs. Requires logind session, and DBUS.enabled = true.
hud_notifications	bool		display HUD notifications on change (requires at least one HUD module).

Config.DBUS.Notifications

Field	Type	Label	Description
enabled	bool		toggles the notification host functionality, required for "notifications" module.

Config.DBUS.Power

Field	Type	Label	Description
enabled	bool		enables power functionality.
low_percent	uint32		percentage below which we should consider low power.
critical_percent	uint32		percentage below which we should consider critical power.
low_command	string		command to execute on low power.
critical_command	string		command to execute on critical power.
hud_notifications	bool		display HUD notifications on power state change or low power.

Config.DBUS.Shortcuts

Field	Type	Label	Description
enabled	bool		enables GlobalShortcuts support.

Config.DBUS.Systray

Field	Type	Label	Description
enabled	bool		toggles the StatusNotifierItem host, required for "systray" module. Must be the only SNI implementation running in the session.

Panel

Field	Type	Label	Description
id	string		unique identifier for this panel.
edge	Edge		screen edge to place this panel.
size	uint32		either width or height in pixels, depending on orientation for screen edge.
monitor	string		monitor to display this panel on.
modules	hyprpanel.module.v1.Module	repeated	list of modules for this panel.

Edge

Name	Number	Description
EDGE_UNSPECIFIED	0
EDGE_TOP	1
EDGE_RIGHT	2
EDGE_BOTTOM	3
EDGE_LEFT	4

LogLevel

Name	Number	Description
LOG_LEVEL_UNSPECIFIED	0
LOG_LEVEL_TRACE	1
LOG_LEVEL_DEBUG	2
LOG_LEVEL_INFO	3
LOG_LEVEL_WARN	4
LOG_LEVEL_ERROR	5
LOG_LEVEL_OFF	6

Top

hyprpanel/module/v1/module.proto

Audio

Field	Type	Label	Description
icon_size	uint32		size in pixels for panel icon.
icon_symbolic	bool		display symbolic or coloured icon in panel.
command_mixer	string		command to execute on mixer button.

Clock

Field	Type	Label	Description
time_format	string		Go time layout string for panel time display formatting, see https://pkg.go.dev/time#pkg-constants for details.
date_format	string		Go time layout string for panel date display formatting, see https://pkg.go.dev/time#pkg-constants for details.
tooltip_time_format	string		Go time layout string for tooltip time display formatting, see https://pkg.go.dev/time#pkg-constants for details.
tooltip_date_format	string		Go time layout string for tooltip time display formatting, see https://pkg.go.dev/time#pkg-constants for details.
additional_regions	string	repeated	list of addtional regions to display in the tooltip.

Hud

Field	Type	Label	Description
notification_icon_size	uint32		size in pixels for icons in notifications.
timeout	google.protobuf.Duration		delay before notifications are hidden (format: "7s").
position	Position		screen position to display notifications.
margin	uint32		space in pixels between notifications.

Module

Field	Type	Label	Description
pager	Pager
taskbar	Taskbar
systray	Systray
notifications	Notifications
hud	Hud
audio	Audio
power	Power
clock	Clock
session	Session
spacer	Spacer

Notifications

Field	Type	Label	Description
icon_size	uint32		size in pixels for the panel notification icon. Currently unused as notification history is unimplemented.
notification_icon_size	uint32		size in pixels for icons in notifications.
default_timeout	google.protobuf.Duration		delay before notifications are hidden, if the notification does not specify a timemout (format: "7s").
position	Position		screen position to display notifications.
margin	uint32		space in pixels between notifications.
persistent	string	repeated	list of application names to retain notification history for. Currently unused as notification history is unimplemented.

Pager

Field	Type	Label	Description
icon_size	uint32		size in pixels for pager window preview application icons.
active_monitor_only	bool		show only workspaces from the monitor the panel is running on.
scroll_wrap_workspaces	bool		when switching workspaces via mouse scroll, wrap to start/end on over-scroll.
scroll_include_inactive	bool		when scrolling workspaces, include inactive workspaces
enable_workspace_names	bool		display workspace name labels.
pinned	string	repeated	list of workspaces names that will always be included in the pager, regardless of activation state. Unfortunately due to limitations in the Hyprland API, workspace names and IDs must match for this to work currently.
ignore_windows	string	repeated	list of window classes that will be excluded from preview on the pager.

Power

Field	Type	Label	Description
icon_size	uint32		size in pixels for panel icon.
icon_symbolic	bool		display symbolic or coloured icon in panel.

Session

Field	Type	Label	Description
icon_size	uint32		size in pixels for panel icon.
icon_symbolic	bool		display symbolic or coloured icon in panel.
overlay_icon_size	uint32		size in pixels for overlay popup icons.
overlay_icon_symbolic	bool		display symbolic or coloured icons in overlay popup.
command_logout	string		command that will be executed for logout action, empty disabled the button.
command_reboot	string		command that will be executed for reboot action, empty disabled the button.
command_suspend	string		command that will be executed for suspend action, empty disabled the button.
command_shutdown	string		command that will be executed for shutdown action, empty disabled the button.

Spacer

Field	Type	Label	Description
size	uint32		size in pixels for this spacer.
expand	bool		expand to fill available space.

Systray

Field	Type	Label	Description
icon_size	uint32		size in pixels for icons in the systray.
menu_icon_size	uint32		size in pixels for menu icons. Currently unused because GNOME developers hate user/developer choice.
auto_hide_statuses	Systray.Status	repeated	list of statuses that should be auto-hidden.
auto_hide_delay	google.protobuf.Duration		delay before new (or status-changed) icons are auto-hidden (format "4s", zero to disable).
pinned	string	repeated	list of SNI IDs that should never be hidden. There's no convention for ID values - if you want to collect IDs, start hyprpanel with LOG_LEVEL_DEBUG and look for SNI registration events.
modules	SystrayModule	repeated	list of modules to dislpay in systray. Currently supported modules: ["audio", "power"]

SystrayModule

Field	Type	Label	Description
audio	Audio
power	Power

Taskbar

Field	Type	Label	Description
icon_size	uint32		size in pixels for task icons.
active_workspace_only	bool		show only tasks from the current workspace.
active_monitor_only	bool		show only tasks from the monitor the panel is running on.
group_tasks	bool		group tasks for the same application into a single icon. Scroll wheel cycles tasks.
hide_indicators	bool		if you're not using pinned tasks, you may wish to hide the running task indicators.
expand	bool		expand this module to fill available space in the panel.
max_size	uint32		maximum size in pixels for this module. Zero means no limit.
pinned	string	repeated	list of window classes that should always be displayed on the taskbar. Allows the taskbar to act as a launcher.

Position

Name	Number	Description
POSITION_UNSPECIFIED	0
POSITION_TOP_LEFT	1
POSITION_TOP	2
POSITION_TOP_RIGHT	3
POSITION_RIGHT	4
POSITION_BOTTOM_RIGHT	5
POSITION_BOTTOM	6
POSITION_BOTTOM_LEFT	7
POSITION_LEFT	8
POSITION_CENTER	9

Systray.Status

Name	Number	Description
STATUS_UNSPECIFIED	0
STATUS_PASSIVE	1
STATUS_ACTIVE	2
STATUS_NEEDS_ATTENTION	3

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)