https://github.com/e-tho/pwmenu
Launcher-driven audio manager for Linux
https://github.com/e-tho/pwmenu
audio cli dmenu fuzzel launcher linux pipewire rofi
Last synced: about 1 month ago
JSON representation
Launcher-driven audio manager for Linux
- Host: GitHub
- URL: https://github.com/e-tho/pwmenu
- Owner: e-tho
- License: gpl-3.0
- Created: 2025-05-30T21:25:23.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T17:56:54.000Z (about 1 month ago)
- Last Synced: 2026-02-28T20:10:36.747Z (about 1 month ago)
- Topics: audio, cli, dmenu, fuzzel, launcher, linux, pipewire, rofi
- Language: Rust
- Homepage:
- Size: 906 KB
- Stars: 78
- Watchers: 1
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
pwmenu
## About
`pwmenu` (**P**ipe**W**ire **Menu**) manages audio through your launcher of choice.
## Dependencies
### Build
- [`Rust`](https://www.rust-lang.org) (includes `cargo`)
- [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config) – For detecting required libraries
- [`clang`](https://clang.llvm.org) – For C bindings generation
- [`pipewire`](https://pipewire.org) – For PipeWire development headers
### Runtime
- [`pipewire`](https://pipewire.org) – PipeWire daemon
- A launcher with `stdin` mode support
#### Optional
- [NerdFonts](https://www.nerdfonts.com) – For font-based icons (default mode)
- [XDG icon theme](https://specifications.freedesktop.org/icon-theme-spec/latest) – For image-based icons (used with `-i xdg`, included with DEs or can be installed manually)
- [Notification daemon](https://specifications.freedesktop.org/notification-spec/latest) – For system notifications (e.g. `dunst`, `fnott`, included with DEs or can be installed manually)
## Compatibility
| Launcher | Font Icons | XDG Icons | Notes |
| --------------------------------------------- | :--------: | :-------: | ------------------------------------------------------------------------------------- |
| [Fuzzel](https://codeberg.org/dnkl/fuzzel) | ✅ | ✅ | XDG icons supported since v1.13.0 |
| [Rofi](https://github.com/davatorium/rofi) | ✅ | 🔄 | XDG icon support pending via [PR #2122](https://github.com/davatorium/rofi/pull/2122) |
| [dmenu](https://tools.suckless.org/dmenu) | ✅ | ❌ | No XDG icon support |
| Custom (stdin) | ✅ | ❔ | Depends on launcher implementation |
> [!TIP]
> If your preferred launcher isn't directly supported, use `custom` mode with appropriate command flags.
## Installation
### Build from source
Run the following commands:
```shell
git clone https://github.com/e-tho/pwmenu
cd pwmenu
cargo build --release
```
An executable file will be generated at `target/release/pwmenu`, which you can then copy to a directory in your `$PATH`.
### Nix
Add the flake as an input:
```nix
inputs.pwmenu.url = "github:e-tho/pwmenu";
```
Install the package:
```nix
{ inputs, ... }:
{
environment.systemPackages = [ inputs.pwmenu.packages.${pkgs.system}.default ];
}
```
### Arch Linux
Install from AUR with your favorite helper:
```shell
paru -S pwmenu-git
```
## Usage
### Supported launchers
Specify an application using `-l` or `--launcher` flag.
```shell
pwmenu -l fuzzel
```
### Custom launchers
Specify `custom` as the launcher and set your command using the `--launcher-command` flag. Ensure your launcher supports `stdin` mode, and that it is properly configured in the command.
```shell
pwmenu -l custom --launcher-command "my_custom_launcher --flag"
```
#### Prompt and Placeholder support
Use `{hint}` as the value for the relevant flag in your command; it will be substituted with the appropriate text as needed.
```shell
pwmenu -l custom --launcher-command "my_custom_launcher --placeholder-flag '{hint}'" # or --prompt-flag '{hint}:'
```
#### Example to enable all features
This example demonstrates enabling all available features in custom mode with `fuzzel`.
```shell
pwmenu -l custom --launcher-command "fuzzel -d --placeholder '{hint}'"
```
### Available Options
| Flag | Description | Supported Values | Default Value |
| -------------------- | --------------------------------------------------------- | -------------------------------------------------------------------- | ------------- |
| `-l`, `--launcher` | Specify the launcher to use (**required**). | `dmenu`, `rofi`, `fuzzel`, `custom` | `None` |
| `--launcher-command` | Specify the command to use when `custom` launcher is set. | Any valid shell command | `None` |
| `-i`, `--icon` | Specify the icon type to use. | `font`, `xdg` | `font` |
| `-s`, `--spaces` | Specify icon to text space count (font icons only). | Any positive integer | `1` |
| `-m`, `--menu` | Specify the root menu to start in. | `output-devices`, `input-devices`, `output-streams`, `input-streams` | `None` |
| `--volume-step` | Specify volume adjustment step as percentage. | `1-25` | `5` |
| `--back-on-escape` | Return to previous menu on escape. | N/A | `false` |
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
## License
This project is licensed under the terms of the GNU General Public License version 3, or (at your option) any later version.
## Support this project
If you find this project useful and would like to help me dedicate more time to its development, consider supporting my work.
[](https://ko-fi.com/e_tho)
[](https://liberapay.com/e-tho)