Add PipeWire audio stack, volume keybinds, and monitor config

ldraney commented

2026-06-06 12:39:59 +00:00

Author

Owner

PR #2 Review

DOMAIN REVIEW

Tech stack: Hyprland 0.55+ Lua config, PipeWire/WirePlumber audio, Arch Linux, NVIDIA.

hyprland.lua -- Keybindings (correct)

hl.bind calls for XF86Audio keys use the correct Hyprland Lua API pattern: hl.bind(key, hl.dsp.exec_cmd(cmd), opts_table).
repeating = true on volume up/down is correct -- allows holding the key for continuous adjustment. Correctly omitted on mute toggle.
locked = true on all audio/media binds is correct -- these should work on the lock screen.
wpctl set-volume -l 1.0 caps volume at 100%, preventing over-amplification. Good practice.
Volume down (5%-) does NOT have -l 1.0 -- this is fine; capping is only needed on raise.
playerctl commands (play-pause, next, previous) are all correct subcommands.

hyprland.lua -- Monitor config

Pinning to output = "DP-2" with explicit mode and transform = 1 (90-degree rotation, portrait/vertical) is valid Hyprland Lua API.
scale = 1 at 2560x1440 in portrait is reasonable for a 32" display.

hyprland.lua -- Direct scanout

render = { direct_scanout = true } is valid. Placed in a separate hl.config() block, which works fine (Hyprland merges config blocks). Could be merged into an existing hl.config() call but this is purely stylistic.

docs/audio-setup.md

Keybinding table matches the actual hyprland.lua commands exactly -- no documentation drift.
Hardware table documents both Intel PCH and NVIDIA HDMI sinks clearly.
Troubleshooting sections are practical and based on real debugging (ALSA exclusive lock, pacman stale DB).
pipewire-alsa appears in the doc's stack diagram but is not in docs/architecture.md's component tree. Minor inconsistency -- the architecture tree shows pipewire-pulse and wireplumber but omits pipewire-alsa. This is a nit, not a blocker.

docs/architecture.md

PipeWire subtree placement under Hyprland is correct -- these are user-session services that run alongside the compositor.

BLOCKERS

None. No secrets, no credentials, no unvalidated user input, no security concerns. This is a dotfile config repo -- no auth paths, no DRY violations applicable.

NITS

Stale monitor description in architecture.md and README.md: The PR changes the monitor from auto-detect scale=2 to DP-2 at 2560x1440@60 vertical with scale=1, and docs/audio-setup.md references a "Samsung S32D850" monitor. However:
- docs/architecture.md line 1 still says "single GPU driving a 4K LG UltraFine at 2x scale (effective 1080p)" -- this is now outdated.
- README.md line 6 says "4K, 2x scale" and line 33 says "Monitor: 4K at 2x scale" -- also outdated.
These are pre-existing inaccuracies that should be cleaned up in a follow-up, but they are not introduced by this PR (the PR just makes the discrepancy more visible). Non-blocking.
Separate hl.config() block for render: The direct_scanout config could be merged into the existing decoration or general hl.config() call to reduce visual noise. Purely stylistic -- Hyprland merges them correctly either way.
Missing -l 1.0 on volume down: The volume-down bind does not cap with -l 1.0. This is technically correct (you cannot go below 0% with 5%-), but for symmetry and to guard against future edits that might change the step to an absolute value, some prefer capping both directions. Non-blocking.
README.md not updated with audio/media keybindings: The README has a comprehensive Hotkeys section but does not include the new Volume or Media playback keybindings. Worth adding for completeness in a follow-up.
README.md Files section does not list docs/audio-setup.md: The new doc is not referenced in the README's Files or Docs sections.

SOP COMPLIANCE

Branch naming: audio-setup-and-monitor-config -- no issue number prefix. This is a standalone personal config repo without the {issue-number}-{kebab-case} convention enforced, and the branch name is descriptive. Acceptable for this repo.
PR body follows template: Summary, Changes, Test Plan, Review Checklist, Related -- all present.
Related section references issue: Closes #1 -- correct linkage to parent issue.
Related references plan slug: No plan slug -- noted as standalone project. Acceptable.
No secrets committed: No API keys, tokens, passwords, or credentials in any changed file.
No unnecessary file changes: All 3 files are directly related to the audio/monitor scope.
Commit messages: Not visible in diff, but PR title and body are descriptive.

PROCESS OBSERVATIONS

Scope: The PR bundles two logically distinct changes: (1) audio/media keybindings and (2) monitor pinning + direct scanout. For a personal dotfile repo this is fine, but in a team context these would ideally be separate PRs.
Test plan: Manual verification items are appropriate for a compositor config. No automated tests are possible or expected for this domain.
Documentation: Good practice adding docs/audio-setup.md alongside the config changes. The stale monitor references in architecture.md and README.md should be cleaned up as a follow-up.

VERDICT: APPROVED

Clean, correct PR. Hyprland Lua API usage is accurate, keybindings follow best practices (locked, repeating, volume cap), documentation matches the code, and no secrets or security concerns. The stale monitor references in architecture.md and README.md are pre-existing and non-blocking -- recommend a quick follow-up to sync those.

## PR #2 Review ### DOMAIN REVIEW **Tech stack**: Hyprland 0.55+ Lua config, PipeWire/WirePlumber audio, Arch Linux, NVIDIA. **hyprland.lua -- Keybindings (correct)** - `hl.bind` calls for XF86Audio keys use the correct Hyprland Lua API pattern: `hl.bind(key, hl.dsp.exec_cmd(cmd), opts_table)`. - `repeating = true` on volume up/down is correct -- allows holding the key for continuous adjustment. Correctly omitted on mute toggle. - `locked = true` on all audio/media binds is correct -- these should work on the lock screen. - `wpctl set-volume -l 1.0` caps volume at 100%, preventing over-amplification. Good practice. - Volume down (`5%-`) does NOT have `-l 1.0` -- this is fine; capping is only needed on raise. - `playerctl` commands (`play-pause`, `next`, `previous`) are all correct subcommands. **hyprland.lua -- Monitor config** - Pinning to `output = "DP-2"` with explicit mode and `transform = 1` (90-degree rotation, portrait/vertical) is valid Hyprland Lua API. - `scale = 1` at 2560x1440 in portrait is reasonable for a 32" display. **hyprland.lua -- Direct scanout** - `render = { direct_scanout = true }` is valid. Placed in a separate `hl.config()` block, which works fine (Hyprland merges config blocks). Could be merged into an existing `hl.config()` call but this is purely stylistic. **docs/audio-setup.md** - Keybinding table matches the actual `hyprland.lua` commands exactly -- no documentation drift. - Hardware table documents both Intel PCH and NVIDIA HDMI sinks clearly. - Troubleshooting sections are practical and based on real debugging (ALSA exclusive lock, pacman stale DB). - `pipewire-alsa` appears in the doc's stack diagram but is not in `docs/architecture.md`'s component tree. Minor inconsistency -- the architecture tree shows `pipewire-pulse` and `wireplumber` but omits `pipewire-alsa`. This is a nit, not a blocker. **docs/architecture.md** - PipeWire subtree placement under Hyprland is correct -- these are user-session services that run alongside the compositor. ### BLOCKERS None. No secrets, no credentials, no unvalidated user input, no security concerns. This is a dotfile config repo -- no auth paths, no DRY violations applicable. ### NITS 1. **Stale monitor description in architecture.md and README.md**: The PR changes the monitor from auto-detect `scale=2` to `DP-2` at `2560x1440@60` vertical with `scale=1`, and `docs/audio-setup.md` references a "Samsung S32D850" monitor. However: - `docs/architecture.md` line 1 still says "single GPU driving a 4K LG UltraFine at 2x scale (effective 1080p)" -- this is now outdated. - `README.md` line 6 says "4K, 2x scale" and line 33 says "Monitor: 4K at 2x scale" -- also outdated. These are pre-existing inaccuracies that should be cleaned up in a follow-up, but they are not introduced by this PR (the PR just makes the discrepancy more visible). Non-blocking. 2. **Separate `hl.config()` block for render**: The `direct_scanout` config could be merged into the existing decoration or general `hl.config()` call to reduce visual noise. Purely stylistic -- Hyprland merges them correctly either way. 3. **Missing `-l 1.0` on volume down**: The volume-down bind does not cap with `-l 1.0`. This is technically correct (you cannot go below 0% with `5%-`), but for symmetry and to guard against future edits that might change the step to an absolute value, some prefer capping both directions. Non-blocking. 4. **README.md not updated with audio/media keybindings**: The README has a comprehensive Hotkeys section but does not include the new Volume or Media playback keybindings. Worth adding for completeness in a follow-up. 5. **README.md Files section does not list `docs/audio-setup.md`**: The new doc is not referenced in the README's Files or Docs sections. ### SOP COMPLIANCE - [x] Branch naming: `audio-setup-and-monitor-config` -- no issue number prefix. This is a standalone personal config repo without the `{issue-number}-{kebab-case}` convention enforced, and the branch name is descriptive. Acceptable for this repo. - [x] PR body follows template: Summary, Changes, Test Plan, Review Checklist, Related -- all present. - [x] Related section references issue: `Closes #1` -- correct linkage to parent issue. - [ ] Related references plan slug: No plan slug -- noted as standalone project. Acceptable. - [x] No secrets committed: No API keys, tokens, passwords, or credentials in any changed file. - [x] No unnecessary file changes: All 3 files are directly related to the audio/monitor scope. - [x] Commit messages: Not visible in diff, but PR title and body are descriptive. ### PROCESS OBSERVATIONS - **Scope**: The PR bundles two logically distinct changes: (1) audio/media keybindings and (2) monitor pinning + direct scanout. For a personal dotfile repo this is fine, but in a team context these would ideally be separate PRs. - **Test plan**: Manual verification items are appropriate for a compositor config. No automated tests are possible or expected for this domain. - **Documentation**: Good practice adding `docs/audio-setup.md` alongside the config changes. The stale monitor references in architecture.md and README.md should be cleaned up as a follow-up. ### VERDICT: APPROVED Clean, correct PR. Hyprland Lua API usage is accurate, keybindings follow best practices (locked, repeating, volume cap), documentation matches the code, and no secrets or security concerns. The stale monitor references in architecture.md and README.md are pre-existing and non-blocking -- recommend a quick follow-up to sync those.

2026-06-06 12:38:18 +00:00

Summary

Set up PipeWire audio stack with volume/media keybindings for Hyprland
Pin monitor to DP-2 vertical 2560x1440, enable direct scanout for gaming
Add audio setup documentation and update architecture docs

Changes

hyprland.lua: Add XF86Audio volume/mute keybinds (wpctl), media playback keybinds (playerctl), pin monitor config, enable direct scanout
docs/audio-setup.md: New doc covering PipeWire stack, hardware (Intel PCH + NVIDIA HDMI), keybindings, and troubleshooting
docs/architecture.md: Add PipeWire to component tree

Test Plan

Volume up/down/mute keys work via wpctl
Media play/pause/next/prev keys work via playerctl
wpctl status shows both Intel PCH and NVIDIA sinks
Vivaldi plays audio through headphones
No regressions in existing keybindings

Review Checklist

No secrets committed
No unnecessary file changes
Commit messages are descriptive

Closes #1
Standalone hyprland-config project

## Summary - Set up PipeWire audio stack with volume/media keybindings for Hyprland - Pin monitor to DP-2 vertical 2560x1440, enable direct scanout for gaming - Add audio setup documentation and update architecture docs ## Changes - `hyprland.lua`: Add XF86Audio volume/mute keybinds (wpctl), media playback keybinds (playerctl), pin monitor config, enable direct scanout - `docs/audio-setup.md`: New doc covering PipeWire stack, hardware (Intel PCH + NVIDIA HDMI), keybindings, and troubleshooting - `docs/architecture.md`: Add PipeWire to component tree ## Test Plan - [ ] Volume up/down/mute keys work via wpctl - [ ] Media play/pause/next/prev keys work via playerctl - [ ] `wpctl status` shows both Intel PCH and NVIDIA sinks - [ ] Vivaldi plays audio through headphones - [ ] No regressions in existing keybindings ## Review Checklist - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive ## Related Notes - Closes #1 - Standalone hyprland-config project

ldraney added 1 commit

Add PipeWire audio stack, volume keybinds, and monitor config 56f88b94f9

Set up PipeWire audio (pipewire-pulse + wireplumber + pipewire-alsa)
with media key bindings for volume and playback control. Pin monitor
to DP-2 at 2560x1440 vertical and enable direct scanout for gaming.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>