Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

FreeBSD volume up key doesn't work

Open
  • Is something wrong?
#461 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
c
Domain
desktop

Research direction

Start in plugins/media-keys/csd-media-keys-manager.c at do_sound_action() and review the volume-step calculations described in the issue. Reproduce the behavior on FreeBSD with pactl and the XF86AudioRaiseVolume key, then verify that repeated volume-up presses continue increasing the volume while Linux behavior remains unchanged.

Written by the indexing model from the issue text.

Description

Cinnamon version: 6.4
cinnamon-settings-daemon version: 6.4.3
OS: FreeBSD 15.0-RELEASE-p9
PulseAudio version: 17.0
Audio backend: module-oss (OSS)
Hardware: Mac Pro 5,1, Realtek ALC889A (multiple PCM devices)

Issue

On FreeBSD, pressing the volume up media key (XF86AudioRaiseVolume) works only once. After the first press, subsequent presses have no effect until volume down is pressed. Volume down works reliably every time. The issue does not occur on Linux.

The root cause is a misalignment between the volume step grid used by csd-media-keys and the volume resolution available through PulseAudio's OSS backend.

Related PR: https://github.com/linuxmint/cinnamon-settings-daemon/pull/460 (tested and working locally)

Steps to Reproduce

  1. Set volume to 50% (e.g. pactl set-sink-volume @DEFAULT_SINK@ 50%).
  2. Press XF86AudioRaiseVolume. Volume increases to ~54%.
  3. Press XF86AudioRaiseVolume again. Volume stays at 54%.
  4. Press XF86AudioRaiseVolume any number of additional times. Volume remains at 54%.
  5. Press XF86AudioLowerVolume. Volume decreases to ~49%.
  6. Press XF86AudioRaiseVolume. Volume increases to ~54% again, then gets stuck.

This was confirmed by simulating key events via XTest and monitoring both PulseAudio (pactl get-sink-volume) and the OSS mixer (mixer -d pcm9) simultaneously. PulseAudio receives change events for every key press, confirming csd-media-keys is sending volume commands -- but the actual volume does not change after the first press.

Expected Behaviour

Each press of volume up should increase the volume by approximately 5%, consistently, regardless of how many times it is pressed in succession.

Root Cause Analysis

The bug is caused by an interaction between three components:

  1. OSS has only 101 discrete volume levels (0-100). PulseAudio's module-oss maps its internal 0-65536 range to these 101 steps. Each OSS step corresponds to ~655 PA units.

  2. csd-media-keys uses grid-aligned stepping. In do_sound_action() (plugins/media-keys/csd-media-keys-manager.c), volume up computes:

    new_vol_pa = MIN(old_vol_pa / vol_step_pa * vol_step_pa + vol_step_pa, max_vol_pa);

    With VOLUME_STEP = 5, vol_step_pa = 65536 * 5 / 100 = 3276. This snaps to a grid of multiples of 3276.

  3. PulseAudio truncates when mapping to OSS levels. When PA sets volume 36036 (the grid target for "55%"), OSS receives 36036 / 65536 = 0.54987..., which truncates to level 54 (not 55). The readback value becomes 35389 (54%).

The result is a cycle:

  • From 35389 (54%): floor(35389 / 3276) * 3276 + 3276 = 10 * 3276 + 3276 = 36036
  • PA sets 36036 -> OSS truncates to level 54 -> readback is 35389
  • Next press computes the same 36036 -> same truncation -> stuck forever

Volume down is not affected because both the floor-rounding in csd-media-keys and the truncation in OSS go in the same direction (downward), so the volume always decreases.

Why this only affects FreeBSD

On Linux, PulseAudio uses ALSA, which has fine-grained volume resolution (65536+ steps). The grid-aligned math lands precisely on the intended value with no truncation. On FreeBSD, PulseAudio uses module-oss, which has only 101 steps. The coarse quantization creates step boundaries that the Cinnamon volume grid (multiples of 3276) systematically falls just short of.

Verified by direct PA volume tests:

Set 36036 (54.99%) -> got 35389 (54.00%)  # 9 units short of boundary
Set 36045 (55.00%) -> got 36044 (55.00%)  # just barely makes it
Set 36044 (55.00%) -> got 35389 (54.00%)  # 1 unit short, truncated

Proposed Fix

On FreeBSD only (#ifdef __FreeBSD__), replace the grid-aligned stepping with simple addition/subtraction in do_sound_action() (plugins/media-keys/csd-media-keys-manager.c):

// Volume up - before (grid-aligned, gets stuck on OSS):
new_vol_pa = MIN(old_vol_pa / vol_step_pa * vol_step_pa + vol_step_pa, max_vol_pa);

// Volume up - after (simple addition, works on OSS):
new_vol_pa = MIN(old_vol_pa + vol_step_pa, max_vol_pa);

// Volume down - before:
new_vol_pa = (old_vol_pa / vol_step_pa * vol_step_pa) - vol_step_pa;

// Volume down - after:
new_vol_pa = old_vol_pa - vol_step_pa;

This matches what pactl set-sink-volume +5% does internally, which was confirmed to work correctly on FreeBSD. The grid-alignment logic is preserved on Linux where ALSA's fine-grained volume resolution (65536+ steps) does not suffer from this truncation issue.

The alternative fix would be in PulseAudio's module-oss to round to nearest instead of truncating when converting PA volumes to OSS levels, but the csd-media-keys fix is simpler and self-contained.

Related Issues

  • linuxmint/cinnamon#10048 - "Volume up keyboard shortcut is not consistent"
  • linuxmint/cinnamon#10269 - "Multimedia key 'volume UP' DEcreases volume at certain preconditions"
  • linuxmint/cinnamon-settings-daemon#362 - Fix for snapping direction (does not address OSS quantization)
Dominant language
C
Stars
70
Forks
78
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from linuxmint/cinnamon-settings-daemon

All issues in linuxmint/cinnamon-settings-daemon

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.