1
┌─────────────────────────────────────────────┐
2
│  你的应用（定义 BaseAudioHandler）          │
3
│  play() / pause() / seek() / skipToNext()   │
4
└──────────────────┬──────────────────────────┘
5
                   │
6
┌──────────────────▼──────────────────────────┐
7
│  audio_service（Dart 抽象层）               │
8
│  .init / mediaItem / playbackState          │
9
└──────────────────┬──────────────────────────┘
10
                   │  AudioServicePlatform.instance
11
┌──────────────────▼──────────────────────────┐
12
│  平台实现（audio_service_platform_interface │
13
│  Android/iOS/macOS 原生 / audio_service_win │
14
└──────────────────┬──────────────────────────┘
15
                   │
16
┌──────────────────▼──────────────────────────┐
17
│  系统媒体会话（Android MediaSession /       │
18
│  Windows SMTC / macOS NowPlaying）          │
19
└─────────────────────────────────────────────┘

1
static AudioServicePlatform _instance =
2
    (!kIsWeb && (Platform.isWindows || Platform.isLinux))
3
        ? NoOpAudioService()
4
        : MethodChannelAudioService();

1
dependencies:
2
  audio_service: ^0.18.0
3
  audio_service_win: ^0.0.3

1
class MyAudioHandler extends BaseAudioHandler with SeekHandler {
2
  // 播放/暂停/上下曲等回调，由你的播放器实现
3
  Future<void>? Function()? onPlay;
4
  Future<void>? Function()? onPause;
5
  Future<void>? Function(Duration position)? onSeek;
6
  Future<void>? Function()? onSkipToNext;
7
  Future<void>? Function()? onSkipToPrevious;
8

9
  @override
10
  Future<void> play() => onPlay?.call() ?? Future.syncValue(null);
11

12
  @override
13
  Future<void> pause() => onPause?.call() ?? Future.syncValue(null);
14

15
  @override
16
  Future<void> seek(Duration position) {
17
    playbackState.add(
18
      playbackState.value.copyWith(updatePosition: position),
19
    );
20
    return onSeek?.call(position) ?? Future.syncValue(null);
21
  }
22

23
  @override
24
  Future<void> skipToNext() => onSkipToNext?.call() ?? Future.syncValue(null);
25

26
  @override
27
  Future<void> skipToPrevious() =>
28
      onSkipToPrevious?.call() ?? Future.syncValue(null);
29
}

1
Future<void> main() async {
2
  WidgetsFlutterBinding.ensureInitialized();
3
  final audioHandler = await AudioService.init(
4
    builder: () => MyAudioHandler(),
5
    config: const AudioServiceConfig(
6
      // 在 Windows 上被用作 SMTC 的 appid
7
      androidNotificationChannelId: 'com.example.myapp.channel.audio',
8
      androidNotificationChannelName: 'Music playback',
9
    ),
10
  );
11
  runApp(MyApp(audioHandler: audioHandler));
12
}

1
// 更新媒体元数据（标题、艺术家、封面）
2
audioHandler.mediaItem.add(MediaItem(
3
  id: 'video-123',
4
  title: '视频标题',
5
  artist: 'UP主',
6
  duration: Duration(minutes: 10),
7
  artUri: Uri.parse('https://example.com/cover.jpg'),
8
));
9

10
// 更新播放状态
11
audioHandler.playbackState.add(PlaybackState(
12
  controls: [
13
    MediaControl.skipToPrevious,
14
    MediaControl.play,
15
    MediaControl.pause,
16
    MediaControl.skipToNext,
17
  ],
18
  processingState: AudioProcessingState.ready,
19
  playing: true,
20
  updatePosition: Duration(seconds: 30),
21
));

1
SMTC 按钮按下
2
  → C++ 层捕获 ButtonPressed
3
  → MethodChannel 'audio_service_win' 发 'onSMTCButtonPressed'
4
  → AudioServiceWin 的 _handlerCallbacks
5
  → 你的 handler.play() / pause() / skipToNext() / ...

1
// configure → 初始化 SMTC
2
await methodChannel.invokeMethod('initializeSMTC', {'appid': ...});
3

4
// setMediaItem → 更新元数据
5
await methodChannel.invokeMethod('setMediaItem', {
6
  'title': ..., 'artist': ..., 'album': ..., 'artUri': ...,
7
});
8

9
// setState → 更新播放状态（0 播放 / 1 暂停 / 2 停止）
10
await methodChannel.invokeMethod('updateState', {'state': state});

1
auto smtc = SystemMediaTransportControls::GetForCurrentView();
2
auto updater = smtc.DisplayUpdater();
3
updater.Type(MediaPlaybackType::Music);
4
updater.MusicProperties().Title(winrt::to_hstring(title));
5
updater.MusicProperties().Artist(winrt::to_hstring(artist));
6
updater.Update();

1
if (artUri 以 http:// 或 https:// 开头) {
2
  // 用 Windows 系统网络栈下载（CreateFromUri）
3
  auto thumbRef = RandomAccessStreamReference::CreateFromUri(uri);
4
  updater.Thumbnail(thumbRef);
5
} else {
6
  // 当作本地文件路径读取（GetFileFromPathAsync）
7
  auto storageFile = StorageFile::GetFileFromPathAsync(localPath).get();
8
  auto thumbRef = RandomAccessStreamReference::CreateFromFile(storageFile);
9
  updater.Thumbnail(thumbRef);
10
}

1
// Android AudioService.java
2
String artCacheFilePath = mediaMetadata.getString("artCacheFile");
3
if (artCacheFilePath != null) {
4
    artBitmap = loadArtBitmap(artCacheFilePath, null);  // 本地文件
5
}

1
// iOS/macOS AudioServicePlugin.m
2
NSString* artCacheFilePath = extras[@"artCacheFile"];
3
UIImage* artImage = [UIImage imageWithContentsOfFile:artCacheFilePath];

1
final artCacheFile = request.mediaItem.extras?['artCacheFile'];
2
final artUri = request.mediaItem.artUri;
3
String? artUriString;
4
if (artCacheFile is String && artCacheFile.isNotEmpty) {
5
  artUriString = artCacheFile;  // 本地文件优先
6
} else if (artUri != null) {
7
  artUriString = artUri.toString();  // 兜底网络 URL
8
}

1
Uri getUri(String? cover) {
2
  String url = ImageUtils.safeThumbnailUrl(cover);
3
  if (Platform.isWindows && url.contains('@') && url.endsWith('.webp')) {
4
    url = '${url.substring(0, url.length - '.webp'.length)}.jpg';
5
  }
6
  return Uri.parse(url);
7
}