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 - Fixed
'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

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.

Chaphasilor · 2026-03-21T20:39:22Z

@APIUM seems like this is coming along nicely! If you resolve the merge conflicts you'll also get CI runs again :)

… example project

Use AlbumArtist endpoint instead of generic Artist endpoint so that performing-only artists (who have no albums) don't appear in the list.

APIUM · 2026-03-22T10:25:41Z

@APIUM seems like this is coming along nicely! If you resolve the merge conflicts you'll also get CI runs again :)

Done! Needs approval to run

Chaphasilor · 2026-03-24T08:26:37Z

also, can you update the todo list at the top to reflect the current status?
oh and don't worry if the code gen - splash screen check fails, that's not your fault

APIUM · 2026-03-25T00:45:28Z

also, can you update the todo list at the top to reflect the current status? oh and don't worry if the code gen - splash screen check fails, that's not your fault

Sorry, didn't see this. Have just pushed the formatting fix.

Chaphasilor

Okay, found some things that should probably be updated, but most things look good from my perspective!

Chaphasilor · 2026-04-06T15:55:50Z

  static const androidStopForegroundOnPause = true;
  static const onlyShowFavorites = false;
  static const trackShuffleItemCount = 250;
+  static const quickShuffleItemCount = 30;


maybe add a description of what this is used for? as in, why do we need this.

Chaphasilor · 2026-04-06T16:18:38Z

+      return;
+    }
+
+    // Fetch 1 random track and start continuous radio from it.


If you want to enable radio, then please rename the method. "Instant Mix" is a specific Jellyfin feature and pre-fetches similar tracks in advance. Radio fetches tracks just-in-time, and the Continuous radio mode does not yield the same results as an instant mix. For that, you should use the "Similar" mode instead.

On the other hand, if this is for the "Instant Mix" quick action, then you should just fetch the items from the correct API instead, or add an itemCount parameter to the existing instant mix method of the audio service helper.

Yeah that's fair. It was for 'Instant Mix' on the UI. I would like to avoid the queue size issue again so I have renamed this Radio Mix

There's no "Radio Mix" - we have "Instant Mix" and "Start Radio" in the UI.
I'm guessing you can't access the translation tokens from CarPlay? If you can, just use the same token that's used in the track or album menu ^^

Chaphasilor · 2026-04-06T16:24:22Z

+  List<FinampQueueItem> getRecentPlays({int limit = 5}) {
+    return _queueService.peekQueue(previous: limit);
+  }


where is this used? If the queue is replaced, this might be an empty list. The playback history service could be another source.

Yeah you're right. It's used on the CarPlay home screen. I have changed it to that.

I didn't really pick up on this, the CarPlay home screen is only built once and there aren't any tracks in there, so it doesn't update. I think I'd rather just make it better in the updated Home Screen so I'm going to leave this as-is (still changing to the playback history service)

Chaphasilor · 2026-04-06T16:39:24Z

+              case TabContentType.genres:
+                showAlbumsTemplate(tabType: parentId.contentType);
+              case TabContentType.artists:
+                showArtistsTemplate();


traditionally genres in Finamp were closer to artists than to albums. What made you use the albums template for them here?

Do you mean you'd get a list of tracks rather than albums? I picked albums as it gives the user a lot more choice with the constrained list length on CarPlay

So am I wrong in assuming that these templates refer to a screen? So that an album template shows the content of a specific album, and an artist template that of a specific artists?
Because in that case, an album would contain tracks, and an artist could contain a mix of tracks and albums, with an emphasis on albums. That's what I meant by "traditionally": before the redesign, the artist screen in Finamp was just a list of albums, and so was the genre screen.

But if this template refers to how list items are rendered, then of course the genres tab should could show genres that look like "albums" when rendered.

Yeah it was a confusing name (since renamed) - yes it's just the list template, not a specific screen. I'd previously only used it for Albums but now it's 'showBrowsableListTemplate' instead.

Komodo5197 · 2026-04-08T15:45:10Z

+  /// Returns a map of imageId -> local file URI string.
+  /// Items sharing the same imageId are downloaded only once.
+  Future<Map<String, String>> _preloadCarPlayImages(List<BaseItemDto> items) async {
+    final Map<String, String> imageUriMap = {};


I think it's better to resolve the URI with something more like _providers.read(albumImageProvider(AlbumImageRequest(item: item, maxHeight: 200, maxWidth: 200))).uri, which is what android auto does. This covers things like the player image cache, which you missed with this logic. By the way, have we verified that carplay doesn't have an internal cache if we give identical URIs repeatedly?

Komodo5197 · 2026-04-08T16:02:56Z

    try mutableDir.setResourceValues(values)
 }
+
+// TODO: This is a workaround because audio_service doesn't set MPNowPlayingInfoCenter.playbackState on iOS.


It looks like there's already a PR fixing this ryanheise/audio_service#1140, so it might be easier to strip this code out and just switch to that fork until it's merged?

I'm worried it won't get merged, it's 7 months old. I'm happy to make a ticket for this and we can update and remove the workaround when it's merged?

If this is not a ton of messy code that could be avoided by this, it's probably better to keep tracking the regular audio_service repo. I'd like to stay up to date with any other fixes there.

Komodo5197 · 2026-04-08T21:40:59Z

+
+/// Maximum items to fetch from server for CarPlay lists.
+/// Keeps UI responsive and avoids memory issues on car displays.
+const _carPlayOnlineLimit = 250;


I notice a lot of the lists seem to just cutoff at this limit, and 250 isn't crazy high. Is there a way to add pagination, or at least an indicator that we've cutoff the list?

Another I'd like to improve later. CarPlay starts to get laggy above around this - AA is the same. I want to be able to load as we go with pagination.

@APIUM FYI there's an open PR that tries to add pagination to AA, although it's a workaround: #1579
Might be worth looking into at least, since the native capabilities of AA (and CarPlay from what you've told me) are really limited.

That was the core concept I was planning to use too - when that's merged then we should have the functions I was missing when I was trying to get this in that made me push it out to a follow up PR. I'll put a link to it in my issue.

Ah I didn't see they were using NameStartsWith - I was having trouble for this use, I've now forgotten as I think there were a couple of issues, but one is that in CarPlay we display by SortName, but that API call doesn't give SortName it gives the regular name so things would show up in the wrong spot. I think there was a bigger showstopper though, it might have been that this causes issues with special characters?

I wouldn't be surprised. Also haven't tested that PR yet.

Chaphasilor · 2026-04-12T21:47:37Z

@UnicornsOnLSD is anything needed on the App Store side if we release this? I'd like to avoid being rejected because we forgot to change some configuration here or in the store settings 😅

UnicornsOnLSD · 2026-04-19T00:23:06Z

There shouldn't be, main thing is getting the entitlement, which we do have (and seems to work in TestFlight builds, which is promising :) )

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

Comment thread lib/services/android_auto_helper.dart Outdated

Comment thread pubspec.lock

Comment thread lib/services/queue_service.dart Outdated

Comment thread ios/Runner/RunnerDebug.entitlements Outdated

Chaphasilor assigned UnicornsOnLSD Jan 24, 2026

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

APIUM force-pushed the pr-1474-flutter-carplay branch 2 times, most recently from c9842c1 to 660c558 Compare March 5, 2026 10:47

Chaphasilor mentioned this pull request Mar 14, 2026

✨ Home Screen #1141

Draft

25 tasks

Chaphasilor reviewed Mar 14, 2026

View reviewed changes

This was referenced Mar 15, 2026

feat: Add Apple CarPlay support #1480

Open

[superseded by #1516] Add CarPlay support #1474

Closed

APIUM force-pushed the pr-1474-flutter-carplay branch from 0a9c32f to 62bc78d Compare March 18, 2026 11:35

llim1 added 8 commits March 22, 2026 21:07

add flutter_carplay package and basic carplay implementation based on…

45d831b

… example project

strip irrelevant sample code from carplay instantiation

adce12b

move to new carplay helper service

8767be4

album browser using android_auto_helper

2d45552

begin switch to direct db access instead of leveraging AndroidAutoHelper

aeeecd4

add carplay playback, artist page (wip)

c93c6f4

fetch album artwork when applicable

22406fb

add offline mode support to root collection fetching

bf42653

APIUM added 8 commits March 22, 2026 21:09

Fix artist listing in CarPlay

d114d9c

Use AlbumArtist endpoint instead of generic Artist endpoint so that performing-only artists (who have no albums) don't appear in the list.

Show albums instead of tracks for genres in CarPlay

71908ef

Fix Siri playback briefly switching to other apps

6efbbf7

Reduce CarPlay shuffle track count to 30

00848c9

Resume playback on CarPlay connect

625ab0d

Fix "song" to "track" in CarPlay Siri hint

9854e32

Switch flutter_carplay to upstream repo

9f2798e

Fix missing CarPlay and Siri plist keys after rebase

622ef6a

APIUM force-pushed the pr-1474-flutter-carplay branch from 62bc78d to 622ef6a Compare March 22, 2026 10:24

Fix dart formatting

dcbf415

Chaphasilor requested changes Apr 6, 2026

View reviewed changes

APIUM mentioned this pull request Apr 8, 2026

Update CarPlay to use MusicScreenProviders #1586

Open

Address review comments

f4d8177

APIUM force-pushed the pr-1474-flutter-carplay branch from 29acc9d to f4d8177 Compare April 8, 2026 12:49

Komodo5197 reviewed Apr 8, 2026

View reviewed changes

This was referenced Apr 9, 2026

Update audio_service when Now Playing is fixed #1590

Open

Create unified AA/Siri/Carplay search function #1591

Open

Allow more than 250 items in a list in CarPlay #1592

Open

Address PR comments

41335fd

Chaphasilor mentioned this pull request Apr 10, 2026

CarPlay Improvements #1594

Open

Merge branch 'redesign' into pr-1474-flutter-carplay

98dff62

APIUM added 3 commits April 21, 2026 23:55

Use albumImageProvider for CarPlay images

57b49a0

Use sortName for CarPlay alphabet bucketing

0dbd8fa

Guard null nav context in Android Auto and queue source

b5ebb17

APIUM force-pushed the pr-1474-flutter-carplay branch from 8b4d3a8 to b5ebb17 Compare April 21, 2026 13:58

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Chaphasilor commented Mar 21, 2026

Uh oh!

APIUM commented Mar 22, 2026

Uh oh!

Chaphasilor commented Mar 24, 2026

Uh oh!

APIUM commented Mar 25, 2026

Uh oh!

Chaphasilor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

APIUM commented Jan 17, 2026 •

edited

Loading