Adds a new song detail view and 30s song preview for tracks from Apple Music.

scottboms · scottboms · commit 24e88bc6fe7d · 2025-08-20T00:47:19.000-07:00
diff --git a/classes/MusicKit.php b/classes/MusicKit.php
@@ -149,6 +149,96 @@ public static function recentlyPlayed(array $opts, array $params = []): Response
 		return $result instanceof Response ? $result : Response::json($result ?? ['data' => []], 200);
 	}
 
+	// get individual track details
+	public static function songDetails(string $songId, string $language = 'en-US'): Response
+	{
+		$opts = static::opts();
+		$dev  = Auth::devToken($opts);
+
+		// option > user's storefront (if available) > 'us'
+		$storefront = option('scottboms.applemusic.storefront');
+		if ($storefront === 'auto' || empty($storefront)) {
+			$sf = 'us';
+			$mut = Auth::readAnyToken(); // optional
+			if ($mut) {
+				$sfRes = static::appleGet('/v1/me/storefront', $dev, $mut, ['Accept-Language' => $language]);
+				$sfJson = json_decode($sfRes->body() ?? 'null', true);
+
+				if (is_array($sfJson) && !empty($sfJson['data'][0]['id'])) {
+					$sf = $sfJson['data'][0]['id'];
+				}
+			}
+			$storefront = $sf ?: 'us';
+		}
+
+		// call catalog: dev token only (no music-user-token necessary)
+		$resp = \Kirby\Http\Remote::get('https://api.music.apple.com/v1/catalog/' . rawurlencode($storefront) . '/songs/' . rawurlencode($songId), [
+			'headers' => [
+				'Authorization'    => 'Bearer ' . $dev,
+				'Accept'           => 'application/json',
+				'Accept-Language'  => $language,
+			],
+			'timeout' => 10,
+		]);
+
+		$code = $resp->code();
+		$body = json_decode($resp->content() ?? 'null', true);
+
+		if ($code >= 400 || !is_array($body)) {
+			return Response::json([
+				'status'  => 'error',
+				'message' => 'Apple Music catalog error',
+				'code'    => $code,
+				'body'    => $body,
+			], $code ?: 500);
+		}
+
+		// normalization for component view
+		$it = $body['data'][0] ?? null;
+		$a  = $it['attributes'] ?? [];
+		$img = null;
+
+		if (!empty($a['artwork']['url'])) {
+			$img = str_replace(['{w}','{h}'], [600, 600], $a['artwork']['url']);
+		}
+		$seconds = isset($a['durationInMillis']) ? (int) floor($a['durationInMillis'] / 1000) : null;
+		$duration = is_int($seconds) ? sprintf('%d:%02d', floor($seconds/60), $seconds % 60) : null;
+
+		// releaseYear from releaseDate
+		$releaseDate = $a['releaseDate'] ?? null;
+		$releaseYear = null;
+		if ($releaseDate) {
+			$ts = strtotime($releaseDate);
+			if ($ts !== false) {
+				$releaseYear = date('Y', $ts);
+			}
+		}
+
+		$id = $it['id'] ?? null;
+		$url = $a['url'] ?? null;
+
+		// if the id starts with "i.", clear the url
+		if (is_string($id) && str_starts_with($id, 'i.')) {
+			$url = null;
+		}
+
+		return Response::json([
+			'id'           => $id,
+			'name'         => $a['name'] ?? '',
+			'artistName'   => $a['artistName'] ?? '',
+			'albumName'    => $a['albumName'] ?? '',
+			'composerName' => $a['composerName'] ?? '',
+			'genreNames'   => $a['genreNames'] ?? [],
+			'releaseDate'  => $releaseDate,
+			'releaseYear'  => $releaseYear,
+			'url'          => $url,
+			'previewUrl'   => $a['previews'][0]['url'] ?? null,
+			'duration'     => $duration,
+			'image'        => $img,
+			'raw'          => $body, // optional: full response payload
+		], 200);
+	}
+
 	/**
 	 * server-side helper for front-end:
 	 * fetches recently played for the shared token, cache it,
diff --git a/index.css b/index.css
diff --git a/index.js b/index.js
diff --git a/index.php b/index.php
@@ -102,7 +102,21 @@
 							]
 						];
 					}
-				]
+				],
+
+				[
+					'pattern'   => 'applemusic/song/(:any)',
+					'action'  => function ($songId) {
+						return [
+							'component' => 'k-musickit-song-view',
+							'props'     => [
+								'songId'   => $songId,
+								'language' => option('panel.language', 'en-US')
+							]
+						];
+					}
+				],
+
 			]
 		]
 	],
diff --git a/lib/routes.php b/lib/routes.php
@@ -168,6 +168,22 @@
 		}
 	],
 
+	// get details for an individual track from the api
+	[
+		'pattern' => 'applemusic/song/(:any)',
+		'method'  => 'GET',
+		'action'  => function (string $songId) {
+			$language = get('l', 'en-US');
+			// ensure options exist (no user token required for catalog lookups)
+			$opts = MusicKit::opts();
+			if ($err = Auth::validateOptions($opts)) {
+				return $err; // 4xx with structured json
+			}
+			$res = MusicKit::songDetails($songId, $language);
+			return $res;
+		}
+	],
+
 	// storefront (delegates to MusicKit::storefront)
 	[
 		'pattern' => 'applemusic/applemusic',
diff --git a/src/components/MusicKitHistory.vue b/src/components/MusicKitHistory.vue
@@ -150,7 +150,8 @@ export default {
 		},
 		collectionItems() {
 			return (this.items || []).map((item) => {
-				const link = this.trackUrl(item);
+				const appleMusicUrl = this.trackUrl(item); // external Apple Music URL (may be null)
+				const isInline = typeof item.id === 'string' && item.id.startsWith('i.');
 
 				const base = {
 					id: item.id,
@@ -162,14 +163,14 @@ export default {
 						cover: true,
 						back: 'pattern'
 					},
-					link,
 					icon: 'music',
-					target: '_blank',
 					title: this.trackSubtitle(item),
+					// only add the panel link if it's not an inline ("i.") id
+					...(isInline ? {} : { link: 'applemusic/song/' + item.id })
 				};
 
 				// only add options if link is present
-				if (link) {
+				if (appleMusicUrl) {
 					base.options = [
 						{
 							icon: 'headphones',
diff --git a/src/components/MusicKitSong.vue b/src/components/MusicKitSong.vue
@@ -0,0 +1,122 @@
+<template>
+	<k-panel-inside>
+		<k-view>
+			<k-header class="k-site-view-header">
+				{{ song?.name || 'Song' }}
+
+				<template #buttons>
+					<k-button v-if="song?.url" icon="headphones" :link="song.url" target="_blank" theme="blue-icon" variant="filled">Listen in Apple Music</k-button>
+				</template>
+			</k-header>
+
+			<k-box v-if="loading" icon="loader">Loading...</k-box>
+			<k-box v-else-if="err" theme="negative" icon="alert">{{ err }}</k-box>
+
+			<k-section v-else>
+
+				<k-grid style="gap: 0; --columns: 12; background: var(--item-color-back); border-radius: var(--rounded); box-shadow: var(--shadow);">
+					<k-image-frame v-if="song.image" :src="song.image" :alt="song.name" ratio="1/1" back="pattern" cover="true" icon="music" style="border-radius: var(--rounded); --width: 1/2" />
+
+					<k-box style="--width: 1/2">
+						<div class="k-text" style="padding: var(--spacing-8)">
+							<p v-if="song.artistName" class="am-songArtist">{{ song.artistName }}</p>
+							<p v-if="song.albumName" class="am-songAlbum">{{ song.albumName }} ({{ song.releaseYear }})</p>
+
+							<k-box v-if="song.duration" icon="clock" class="am-songDuration">{{ song.duration }}</k-box>
+
+							<k-box v-if="song.previewUrl">
+								<audio :src="song.previewUrl" class="k-file-preview am-audioPreview" controls />
+							</k-box>
+
+							<hr />
+
+							<k-box v-if="song.composerName" icon="composer" class="am-meta am-metaSmall">Written by {{ song.composerName }}</k-box>
+							<k-box v-if="song.genreNames?.length" icon="tag" class="am-meta am-metaSmall">{{ song.genreNames.join(', ') }}</k-box>
+							<k-box v-if="song.releaseDate" icon="calendar" class="am-meta am-metaSmall">{{ song.releaseDate }}</k-box>
+						</div>
+					</k-box>
+				</k-grid>
+
+			</k-section>
+
+		</k-view>
+	</k-panel-inside>
+</template>
+
+<script>
+export default {
+	name: 'Apple Music - Song Details',
+	props: {
+		songId: String,
+		language: String
+	},
+
+	data() {
+		return {
+			loading: true,
+			err: null,
+			song: null
+		};
+	},
+
+  async created() {
+    try {
+			const url = `/applemusic/song/${encodeURIComponent(this.songId)}?l=${encodeURIComponent(this.language || 'en-US')}`;
+			const res = await fetch(url, {
+				credentials: 'same-origin',
+				headers: { 'Accept': 'application/json' }
+			});
+			if (!res.ok) throw new Error(`HTTP ${res.status}`)
+				const data = await res.json();
+				this.song = data;
+		} catch (e) {
+			this.err = e?.message || 'Failed to load song'
+		} finally {
+			this.loading = false
+		}
+	},
+
+	methods: {
+		back() { this.$go('applemusic') }
+	},
+
+}
+</script>
+
+<style>
+.am-songArtist {
+	font-size: var(--text-4xl);
+}
+
+.am-songAlbum {
+	font-size: var(--text-2xl);
+	margin-top: var(--spacing-2);
+}
+
+.am-songAlbum,
+.am-songDuration {
+	color: light-dark(var(--color-gray-650), var(--color-gray-450));
+}
+
+.am-songDuration {margin-top: var(--spacing-2);}
+
+.am-songDuration,
+.am-songComposer {
+	font-size: var(--text-lg);
+}
+
+.am-audioPreview {
+	background: none;
+	margin: var(--spacing-4) 0;
+	width: 25%;
+}
+
+.am-metaSmall {
+	font-size: var(--text-sm);
+}
+
+.am-meta {
+	color: light-dark(var(--color-gray-500), var(--color-gray-700));
+	margin-top: var(--spacing-2);
+}
+</style>
diff --git a/src/icons.js b/src/icons.js
diff --git a/src/index.js b/src/index.js
@@ -2,6 +2,7 @@ import AppleMusicField from "./components/AppleMusicField.vue";
 import AppleMusicBlock from "./components/AppleMusicBlock.vue";
 import MusicKitConfig  from "./components/MusicKitConfig.vue";
 import MusicKitHistory from "./components/MusicKitHistory.vue";
+import MusicKitSong    from "./components/MusicKitSong.vue";
 
 import { icons }       from "./icons.js";
 
@@ -10,6 +11,7 @@ panel.plugin("scottboms/kirby-applemusic", {
 	components: {
 		"k-musickit-config-view": MusicKitConfig,
 		"k-musickit-history-view": MusicKitHistory,
+		"k-musickit-song-view": MusicKitSong,
 	},
 	fields: {
 		applemusic: AppleMusicField

Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,21 @@`
`102`	`102`	`]`
`103`	`103`	`];`
`104`	`104`	`}`
`105`		`- ]`
	`105`	`+ ],`
	`106`	`+`
	`107`	`+ [`
	`108`	`+ 'pattern' => 'applemusic/song/(:any)',`
	`109`	`+ 'action' => function ($songId) {`
	`110`	`+ return [`
	`111`	`+ 'component' => 'k-musickit-song-view',`
	`112`	`+ 'props' => [`
	`113`	`+ 'songId' => $songId,`
	`114`	`+ 'language' => option('panel.language', 'en-US')`
	`115`	`+ ]`
	`116`	`+ ];`
	`117`	`+ }`
	`118`	`+ ],`
	`119`	`+`
`106`	`120`	`]`
`107`	`121`	`]`
`108`	`122`	`],`