Skip to content

omalauncher media: Linux players in Android's media controls (lock screen, car, headset buttons) - #267

Open
petrzpav wants to merge 4 commits into
SimonSchubert:mainfrom
petrzpav:linux-media-session
Open

petrzpav wants to merge 4 commits into
SimonSchubert:mainfrom
petrzpav:linux-media-session

Conversation

@petrzpav

@petrzpav petrzpav commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Guest audio already plays as Android media (AudioBridge), but to the phone nothing is playing: no lock-screen player, nothing in the notification shade, a car shows no track over Bluetooth and its steering-wheel buttons, a headset's or AirPods' presses go to whatever Android app played last. This lets a Linux player say what it plays with omalauncher media, and the launcher publishes it as an Android media session. Closes #122.

omalauncher media set '{"title": "Ace Ventura full set @ Boom Festival 2016", "artist": "Ace Ventura", "album": "SoundCloud",
  "art": "https://i1.sndcdn.com/artworks-000219900249-gzmwnm-t500x500.jpg", "duration": 19033, "position": 7380,
  "playing": true, "command": "myplayer-ctl"}'
omalauncher media set '{"playing": false, "position": 7421}'   # no title: changes only these fields
omalauncher media                                            # what's set, the position as of now
omalauncher media clear                                      # prints nothing, like notify

A press anywhere (lock screen, shade, car, headset, watch) runs the player's command in Linux with the action after it: myplayer-ctl play|pause|next|previous|stop or myplayer-ctl seek 120. actions limits which ones the player offers (default all but stop); without a command the session shows the track and offers none. Each press is shown at once (playing/paused, where a seek went) until the player's next set.

How

  • LinuxMedia.kt: a platform MediaSession (no new dependency) with metadata, PlaybackState (position, speed and update time, so Android runs the clock) and a MediaStyle notification on its own low-importance channel, "Playing from Linux". The cover comes from an https URL or a file in Linux, scaled to ≤512 px, once per track. Before Android 13 the notification's own buttons go through a not-exported receiver; from 13 on Android draws them from the session.
  • PhoneBridge: media, media set <json>, media clear, in the same inbox as location, calendar and airpods. A set that isn't one JSON object, has an unknown field, or has no title while nothing is set answers usage: (exit 2), naming why. media is in COMMANDS, so omalauncher version lists it.
  • omalauncher.sh: the usage text and the argument check. Requests end each argument with a NUL now, so a JSON object written over several lines goes as it is. OmalauncherScriptTest.mediaSendsItsJsonWhole checks that, and commandsAgree covers the new command.
  • Runtime: creates it lazily and clears it when Linux is removed. The guest's AGENTS.md paragraph on omalauncher and the README's section mention it, so agents know a player can do this.

Not in this PR: Android Auto's browsing (needs a MediaBrowserService), audio focus (a call or another app playing doesn't pause the guest; the guest's player still decides), and MPRIS: there's no session D-Bus in the guest; a small playerctl-based adapter could drive omalauncher media later.

Tested

After merging main (1.3.0, at 30f208c): ./gradlew :owl:test :app:testDebugUnitTest :owl:owlJar and ./gradlew :app:assembleDebug :app:lintDebug pass, OmalauncherScriptTest included (15 tests, with the new mediaSendsItsJsonWhole). Not run on the phone again since the port: LinuxMedia is unchanged, and the port changes only the command's name, the NUL-ended request and the usage: answers.

Before the rename (on 0.20.0, when the command was still phone), on a Pixel 9 Pro XL (Android 17), as the side-by-side debug copy with Linux set up, driving the inbox over adb run-as as the script does (the play command only logged its arguments) and tapping the system player's buttons:

Lock screen Notification shade, playing Paused
lock screen shade, playing shade, paused
  • media set with a SoundCloud set (5 h 17 min, its cover by https URL): the session is active and PLAYING at 2:03:00 with title, artist, album and duration; the shade's and the lock screen's player show it with the cover, the clock running on.
  • The shade's buttons, tapped: pause, next, previous and play each ran <command> <action> in Linux, in that order; tapping 70% along the seek bar ran <command> seek 13266 and the player went there at once. Paused shows play and a still bar.
  • {"playing": false, "position": 7421} (no title) changed only those; a set with an unknown field, or not an object, or without a title while nothing is set, answers an error naming why.
  • media clear: the notification and the session are gone; media answers null.
  • Not tested here: a car over Bluetooth and headset buttons. cmd media_session dispatch sends keys to the app Android last heard playing audio, and the test copy played none; with a guest player's audio going through AudioBridge that's this app.

🤖 Generated with Claude Code

…hone media set` with a track's title, artist, album, cover (an https URL or a file in Linux), length, position, speed and whether it plays publishes a media session and its notification, so the lock screen, the notification shade's player, a car's display and steering-wheel buttons over Bluetooth, a watch and headset and AirPods buttons show and steer it; a press runs the player's command in Linux with the action after it (play, pause, next, previous, stop, or seek and the second), and is shown at once until the player's next set; a set without a title changes only the fields it has, as a player says it paused, and `phone media clear` takes it away, as removing Linux does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@petrzpav
petrzpav marked this pull request as ready for review November 6, 2026 17:17
t1nk333r pushed a commit to t1nk333r/omalauncher that referenced this pull request Nov 10, 2026
…droid's media controls (lock screen, car, headset buttons)

Ported onto the omalauncher command (phone.sh is gone since 0.20): `omalauncher media` is one of its commands, its wrong arguments answer as usage (exit 2), and stopping Linux clears the player as removing it does.
…nd's rename (c6163e3): its usage and argument check are in omalauncher.sh, it's in COMMANDS, the README and the guest's AGENTS.md, a JSON written over several lines goes as it is (requests end each argument with a NUL now), a set the launcher can't take answers usage (exit 2), and the CHANGELOG entry goes, as entries come with a release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@petrzpav petrzpav changed the title phone media: Linux players in Android's media controls (lock screen, car, headset buttons) omalauncher media: Linux players in Android's media controls (lock screen, car, headset buttons) Nov 12, 2026
@petrzpav

Copy link
Copy Markdown
Contributor Author

Hi Simon, I updated this to current main: it's omalauncher media now after the phone → omalauncher rename, and CI is green again. It's what #122 asks for, and since the launcher installs cliamp anyway, a small follow-up could put the stock player on the lock screen too. I'd really like to have it for my cliamp widget. Happy for you to reshape it however you like, like you did with #228.

petrzpav and others added 2 commits November 18, 2026 10:50
…neBridge's NOTIFY_CHANNEL is gone, after the shared-to-Linux and one-notification-helper changes (f29cdc3, 4d2cf3f); LinuxMedia imports registerNotExported from dev.omalauncher.system, where the source tree reorganisation moved it (40c8a10)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and Japanese too, as lint asks now that main speaks them (SimonSchubert#267)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.

Guest media: expose proot audio playback to Android media controls (MediaSession)

1 participant