CarPlay Support w/ llim1 base by APIUM · Pull Request #1516 · UnicornsOnLSD/finamp

APIUM · 2026-01-17T03:22:13Z

Adds CarPlay support using flutter_carplay package.

This PR is based on the work from llim1 #1474 adding the finishing touches to get it ready to merge.

Todo before merging

Known issues

Will cross off issues here once they are addressed.

flutter_carplay loads images from web URIs but file URIs are broken despite file paths being listed as supported
'now-playing' screen has inconsistent behaviour on iOS simulator. Need build to physical hardware to test
'now-playing' button in root tab view is missing the icon, despite being clickable
Translations
Extended CONTRIBUTING.md

Related Issues

Closes #24
Original PR #1474

llim1

Some comments, also a few notes:

known issue "flutter_carplay loads images from web URIs but file URIs are broken despite file paths being listed as supported" is marked as fixed but issue is still present in my environment. Some artwork shows a '?' image where visible
jellyfin api related changes not reviewed
siri search not tested

lib/services/android_auto_helper.dart

pubspec.lock

lib/services/queue_service.dart

ios/Runner/RunnerDebug.entitlements

APIUM · 2026-01-23T06:08:14Z

Thanks for the review @llim1

known issue "flutter_carplay loads images from web URIs but file URIs are broken despite file paths being listed as supported" is marked as fixed but issue is still present in my environment. Some artwork shows a '?' image where visible

I misunderstood this originally, I am now able to recreate it, when there were spaces encoded in the url it broke. I've added a fix for this.

llim1 · 2026-01-31T01:12:29Z

Thanks for the review @llim1

known issue "flutter_carplay loads images from web URIs but file URIs are broken despite file paths being listed as supported" is marked as fixed but issue is still present in my environment. Some artwork shows a '?' image where visible

I misunderstood this originally, I am now able to recreate it, when there were spaces encoded in the url it broke. I've added a fix for this.

Confirmed, images issue is fixed. No further comments from me 👍

Chaphasilor · 2026-02-01T20:29:04Z

@APIUM @llim1 do any of you already have access to the entitlements? I think Logan hasn't created the developer account yet, but what about Algy?

Chaphasilor · 2026-02-01T20:31:17Z

@APIUM you mentioned on Discord that we can go back to using the upstream plugin instead of your fork, right?

APIUM · 2026-02-01T21:20:45Z

@APIUM you mentioned on Discord that we can go back to using the upstream plugin instead of your fork, right?

Yep I’ll make this change in here

APIUM · 2026-02-01T21:24:01Z

@APIUM @llim1 do any of you already have access to the entitlements? I think Logan hasn't created the developer account yet, but what about Algy?

I’m waiting on Apple to approve my personal account, they look about 3 days to ask for ID, and it’s been over a week since then. They say it’s a 2 day process…. I’m all set up in the team so I’ll be able to test very quickly once Apple approves.

networkoctopus · 2026-02-06T22:30:14Z

really looking forward to this in Finamp. Thanks for working on it!

Can I cheekily request having an instant mix button available on CarPlay. Would love if it was easy to start a good mix (especially for those who use the new audiomuse-ai backend).

Haar · 2026-02-22T00:26:52Z

Just been running this PR locally on a Simulator before trying it out on actual Hardware. Quick question - what's the difference between Shuffle all and Instant Mix?

APIUM · 2026-02-22T10:26:42Z

Just been running this PR locally on a Simulator before trying it out on actual Hardware. Quick question - what's the difference between Shuffle all and Instant Mix?

Hi @Haar thanks for having a look.

Shuffle all is just a standard shuffle of all the music in your library.
Instant Mix seeds a Jellyfin 'Instant Mix' with a random album from a list of 10. That list is made from 5 random albums, and 5 frequently played albums. I think this behavior will change as I think Chaphasilor is working on some Instant Mix functionality in the home screen redesign.

@networkoctopus see above for the current Instant Mix situation

Harr please let me know if you find a way to test on real hardware, I am having trouble with profiles and certificates. Still working this out and it's why this PR has stalled.

… example project

@objc

Add scene-based lifecycle support for flutter_carplay plugin: - Fix UIApplicationSceneManifest preservation in built Info.plist - Add scene configurations for main app and CarPlay - Implement programmatic scene delegate configuration - Create custom CarPlaySceneDelegate wrapper class Status: App launches without crashes, CarPlay connects but shows blank screen due to plugin delegate not being @objc accessible.

@objc

Make FlutterCarPlaySceneDelegate @objc accessible by modifying plugin source to add @objc annotation. This allows iOS to find the delegate class via NSClassFromString and properly instantiate it for CarPlay scenes. The modification is in pub cache at: .pub-cache/hosted/pub.dev/flutter_carplay-1.2.1/ios/Classes/ FlutterCarplayPluginSceneDelegate.swift (line 24) Change: class FlutterCarPlaySceneDelegate To: @objc(FlutterCarPlaySceneDelegate) class FlutterCarPlaySceneDelegate This fix enables full CarPlay functionality including template rendering and Flutter communication via the plugin's event stream.

- Show login prompt on CarPlay when user is not authenticated - Refresh CarPlay template automatically on login/logout - Add tracks library view with shuffle all option - Implement artist tracks fetching via direct API calls - Wire up playback for artist top tracks and recently played - Set artCacheFile extra for iOS Now Playing artwork display

Add method channel to sync playback state to MPNowPlayingInfoCenter on iOS. This fixes CarPlay not reflecting play/pause state when playback is started from the phone. Workaround for audio_service not setting playbackState on iOS.

Pass null instead of string "null" when imageUri is unavailable to prevent flutter_carplay from trying to load a non-existent asset.

@objc

Switch to APIUM/flutter_carplay fork which adds the @objc annotation to FlutterCarPlaySceneDelegate. This is required for iOS to discover the class via NSClassFromString when specified in the scene manifest. Without this fix, CarPlay fails to initialize because the delegate class cannot be instantiated at runtime. Fork: https://github.com/APIUM/flutter_carplay

Add _isPushing guard to all CarPlay show*Template methods to prevent duplicate template pushes when users tap navigation items quickly. Also add CarPlay development documentation to CONTRIBUTING.md with troubleshooting steps for when CarPlay doesn't appear in the simulator. Committed at 08:46:31

- Shuffle All and Start a Mix buttons at the top - Recent Plays section showing last played tracks from queue - Recently Added section showing 3 most recent albums - Offline mode support for all sections

Use similar list limitation to Android Auto of 250. Users should use search for now for large libraries, and we should update Jellyfin in the future to be able to get items by their first letter server side.

Enable voice commands like "Hey Siri, play [song/artist/album] on Finamp" for CarPlay. Uses SiriKit Media Intents to bridge to the existing Android Auto search logic.

Updated commit author/committer in fork to use proper email address.

- Extract CarPlay item limits to named constants - Improve instant mix: use frequent + random albums instead of recent - Fix lint warnings - Remove verbose NSLog statements, keep error logs - Fix minor code style issues

Also add alphabetical grouping to Tracks and Artists screens.

- Reset pubspec.lock to redesign base, add only flutter_carplay - Remove unused RunnerDebug.entitlements - Revert android_auto_helper.dart playFromMediaId signature - Remove unused artCacheFile from queue_service.dart

Add smtc_windows prefix to avoid conflict with Flutter's new RepeatMode class.

- Fix Siri "not supported" error (add INPlayMediaIntentHandling) - Parallelise CarPlay home screen loading - Optimise instant mix (single track + continuous radio) - Optimise shuffle all (reduced to 30 tracks) - Pre-cache and deduplicate CarPlay cover art

- Add application(_:handlerFor:) intent dispatch method - Change response code from .handleInApp to .success - Add INSupportedMediaCategories to Info.plist files - Remove unused INAddMediaIntent - Use fast 30-track shuffle for Siri (matching CarPlay)

APIUM force-pushed the pr-1474-flutter-carplay branch 2 times, most recently from a7c7134 to b2a397f Compare January 17, 2026 03:58

llim1 reviewed Jan 22, 2026

View reviewed changes

lib/services/android_auto_helper.dart Outdated Show resolved Hide resolved

pubspec.lock Show resolved Hide resolved

lib/services/queue_service.dart Outdated Show resolved Hide resolved

ios/Runner/RunnerDebug.entitlements Outdated Show resolved Hide resolved

Chaphasilor assigned UnicornsOnLSD Jan 24, 2026

llim1 and others added 17 commits February 25, 2026 11:35

add flutter_carplay package and basic carplay implementation based on…

423f1cb

… example project

strip irrelevant sample code from carplay instantiation

871d32f

move to new carplay helper service

0422dd9

album browser using android_auto_helper

1f1112f

begin switch to direct db access instead of leveraging AndroidAutoHelper

155e3f5

add carplay playback, artist page (wip)

7ac6d8a

fetch album artwork when applicable

e7daed6

add offline mode support to root collection fetching

4509fbd

quick add playlists and genres library views

547759c

Fix CarPlay Now Playing playback state sync

0c653f1

Add method channel to sync playback state to MPNowPlayingInfoCenter on iOS. This fixes CarPlay not reflecting play/pause state when playback is started from the phone. Workaround for audio_service not setting playbackState on iOS.

Fix CarPlay crash when image URI is null

9af7373

Pass null instead of string "null" when imageUri is unavailable to prevent flutter_carplay from trying to load a non-existent asset.

Don't load top tracks for artists

9c6a56c

APIUM added 11 commits February 25, 2026 11:35

Add CarPlay Home tab with quick actions and recently added albums

16e43ec

- Shuffle All and Start a Mix buttons at the top - Recent Plays section showing last played tracks from queue - Recently Added section showing 3 most recent albums - Offline mode support for all sections

Update CarPlay library browsing with 250 item limits

5bed9ba

Use similar list limitation to Android Auto of 250. Users should use search for now for large libraries, and we should update Jellyfin in the future to be able to get items by their first letter server side.

Add Siri voice search for CarPlay

b006ad8

Enable voice commands like "Hey Siri, play [song/artist/album] on Finamp" for CarPlay. Uses SiriKit Media Intents to bridge to the existing Android Auto search logic.

Remove unimplemented Recent tab from CarPlay

1def3ae

Update flutter_carplay fork reference

7d11185

Updated commit author/committer in fork to use proper email address.

Separate Siri from CarPlay

2b6908b

Clean up CarPlay and iOS code

04e3c9c

- Extract CarPlay item limits to named constants - Improve instant mix: use frequent + random albums instead of recent - Fix lint warnings - Remove verbose NSLog statements, keep error logs - Fix minor code style issues

Add localisation support

eca93cb

Disable CarPlay home screen section index

2dc5e50

Also add alphabetical grouping to Tracks and Artists screens.

Address PR review comments

572e518

- Reset pubspec.lock to redesign base, add only flutter_carplay - Remove unused RunnerDebug.entitlements - Revert android_auto_helper.dart playFromMediaId signature - Remove unused artCacheFile from queue_service.dart

Update flutter_carplay to fix file URI percent-encoding

e053219

APIUM force-pushed the pr-1474-flutter-carplay branch from 525c5d6 to e053219 Compare February 25, 2026 00:48

APIUM added 2 commits February 25, 2026 12:50

Fix RepeatMode name collision with Flutter 3.41

6934775

Add smtc_windows prefix to avoid conflict with Flutter's new RepeatMode class.

APIUM force-pushed the pr-1474-flutter-carplay branch from 694c91b to 0488123 Compare March 4, 2026 10:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CarPlay Support w/ llim1 base#1516

CarPlay Support w/ llim1 base#1516
APIUM wants to merge 31 commits intoUnicornsOnLSD:redesignfrom
APIUM:pr-1474-flutter-carplay

APIUM commented Jan 17, 2026 •

edited

Loading

Uh oh!

llim1 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

APIUM commented Jan 23, 2026

Uh oh!

llim1 commented Jan 31, 2026

Uh oh!

Chaphasilor commented Feb 1, 2026

Uh oh!

Chaphasilor commented Feb 1, 2026

Uh oh!

APIUM commented Feb 1, 2026

Uh oh!

APIUM commented Feb 1, 2026

Uh oh!

networkoctopus commented Feb 6, 2026

Uh oh!

Haar commented Feb 22, 2026

Uh oh!

APIUM commented Feb 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

APIUM commented Jan 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

llim1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

APIUM commented Jan 23, 2026

Uh oh!

llim1 commented Jan 31, 2026

Uh oh!

Chaphasilor commented Feb 1, 2026

Uh oh!

Chaphasilor commented Feb 1, 2026

Uh oh!

APIUM commented Feb 1, 2026

Uh oh!

APIUM commented Feb 1, 2026

Uh oh!

networkoctopus commented Feb 6, 2026

Uh oh!

Haar commented Feb 22, 2026

Uh oh!

APIUM commented Feb 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

APIUM commented Jan 17, 2026 •

edited

Loading