Skip to content

Software Manual: separate input and output device selection on macOS - #1163

Open
jshipman42 wants to merge 2 commits into
jamulussoftware:next-releasefrom
jshipman42:docs/macos-input-output-devices
Open

jshipman42 wants to merge 2 commits into
jamulussoftware:next-releasefrom
jshipman42:docs/macos-input-output-devices

Conversation

@jshipman42

Copy link
Copy Markdown

Disclosure

This change was written with Claude (Claude Code); the commits carry Co-Authored-By: Claude Opus 5 trailers, the same as jamulussoftware/jamulus#3908. I set the goal and the constraints and reviewed the wording line by line against the style guide; the screenshot is from my own machine. Noting it for transparency, not as a substitute for your review.

Short description of changes

Documents the change in jamulussoftware/jamulus#3908, which replaces the single "Audio Device" menu on macOS with separate "Input Device" and "Output Device" menus. @pljones asked for the documentation to land alongside it.

Adds a short section under Settings / Audio-Network Setup describing the two menus, and reworks the opening of "Audio Device" so it names both layouts up front rather than describing the Windows one and mentioning macOS as an aside. The existing sentence about ASIO is unchanged, so its translations are unaffected.

Two commits: the text, then the screenshot.

Context: Fixes an issue? Related issues

Documents jamulussoftware/jamulus#3908, requested in jamulussoftware/jamulus#3908 (comment).

Status of this Pull Request

Working implementation. Depends on jamulussoftware/jamulus#3908 — please don't merge before it, or the manual will describe a dialog that isn't shipped yet.

What is missing until this pull request can be merged?

Review. Built locally with Jekyll and checked in a browser: the new section renders and the image loads. The screenshot is macOS 26.5, 295 x 136.

Does this need translation?

YES - hence targeting next-release. Four new paragraphs and one new heading; one existing sentence loses a trailing clause that described the old macOS behaviour.

Checklist

  • I've verified that this Pull Request follows the general code principles
  • I waited some time after this Pull Request was opened and all GitHub checks completed without errors.
  • I'm sure that this Pull Request goes to the correct branch

jamulussoftware/jamulus#3908 replaces the single "Audio Device" menu on
macOS with separate "Input Device" and "Output Device" menus.

Add a section describing them, and adjust the "Audio Device" section so
it names both layouts up front instead of describing the Windows one and
mentioning macOS as an aside. The screenshot follows in a separate
commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012i8guRg33BV5Prf7tqkkcH
@jshipman42

Copy link
Copy Markdown
Author

Screenshot for the new section, uploaded here rather than to a throwaway issue — the reason may be worth knowing.

The README (Adding screenshots) says to open an issue anywhere, upload the image, copy the URL and discard the issue. That worked with user-images.githubusercontent.com, where an upload became a standalone object. GitHub has since moved to user-attachments/assets, and those appear to be scoped to the thing they were posted in.

I tried the documented route first and the URL was dead. Testing it properly on my own fork, with an identical browser user-agent throughout:

  • uploaded but never posted → 404
  • same image, comment posted → 200
  • an existing image of yours (settings-midi.inc) → 200

So the upload publishes only when the comment is saved. It seems to have gone unnoticed because nobody has needed to follow the recipe since the change — the 27 newer images all arrived inside PRs (#1095, #1003) and persist because the PRs do, while the older 194 are legacy URLs and unaffected.

This one is therefore attached to the PR that uses it. Happy to send a README tweak, or to move the image elsewhere if you'd rather.

For what it's worth, the reasoning in #554 holds up well. PNGs are ~26.7 MB of ~47 MB of packed objects across this repo's whole history — 57%, from 409 blobs — while 12,388 HTML blobs pack to ~13 MB. The current checkout has only 25 PNGs totalling 0.28 MB, so almost all of it is history from before the migration. Avoiding committed screenshots was the right call.

input-output-devices-macos

Uploaded to this pull request rather than to a discarded issue, because
GitHub's user-attachments URLs are only published once the containing
comment is saved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012i8guRg33BV5Prf7tqkkcH
Comment thread wiki/en/Software-Manual.md Resolved
@pljones

pljones commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Oh, does this only cover macOS for now or is iOS covered, too? If it does cover iOS, could you post screenshots.

Also, could you check the current documentation. In many cases, the whole window or screen is used as the example, rather than a snippet. If we've done it differently here that's fine, otherwise please follow the existing style.

@jshipman42

Copy link
Copy Markdown
Author

Thanks @pljones — both answered below.

iOS

macOS only. iOS has its own sound code and isn't affected, so there's nothing to
screenshot. The PR leaves ASIO, JACK and oboe alone too.

Whole window or a snippet?

Most of the manual shows whole windows, but not all of it — the LEDs, the mixer
channels, the profile tooltip and channel-mapping are all crops, and
channel-mapping is a crop of this same dialog a couple of sections further
down.

I'd keep the crop here because a full macOS window would be confusing. Only this
one control differs on macOS; the rest of the dialog is identical. A full window
invites the reader to compare everything and wonder what else changed, when
nothing did.

It also starts something bigger. Once the page shows one OS's window, the next
step is a page per platform, or a way to pick your OS and have the text and
images follow. That's close to your point below about only showing this section
when there's a choice to make, and it's a rework of the manual rather than a few
lines about two menus.

I have a full-window macOS screenshot if you'd rather use it — one line to swap.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants