fix: Improve Error handling for Unsupported Sources (#1625)

# Description

- feat: Improved error description for unsupported file formats
- fix: Handle white space and special characters in URL and Assets (Web
& Darwin)
- test: Test files without file extension (not playable Darwin)

## Related Issues

Closes #1494
Closes #748
Closes #972
Closes #1546

---------

Co-authored-by: Lukas Klingsbo <lukas.klingsbo@gmail.com>

Author: Gustl22

packages/audioplayers/example/assets/coins whitespace.wav

@@ -31,6 +31,11 @@ final wavUrl1TestData = LibSourceTestData(
   duration: const Duration(milliseconds: 451),
 );
 
+final specialCharUrlTestData = LibSourceTestData(
+  source: UrlSource(wavUrl3),
+  duration: const Duration(milliseconds: 451),
+);
+
 final mp3Url1TestData = LibSourceTestData(
   source: UrlSource(mp3Url1),
   duration: const Duration(minutes: 3, seconds: 30, milliseconds: 77),
@@ -57,6 +62,16 @@ final invalidAssetTestData = LibSourceTestData(
   duration: null,
 );
 
+final specialCharAssetTestData = LibSourceTestData(
+  source: AssetSource(specialCharAsset),
+  duration: const Duration(milliseconds: 451),
+);
+
+final noExtensionAssetTestData = LibSourceTestData(
+  source: AssetSource(noExtensionAsset),
+  duration: const Duration(milliseconds: 451),
+);
+
 final nonExistentUrlTestData = LibSourceTestData(
   source: UrlSource('non_existent.txt'),
   duration: null,

packages/audioplayers/example/assets/coins_no_extension

@@ -1,4 +1,5 @@
 import 'package:audioplayers/audioplayers.dart';
+import 'package:audioplayers_example/tabs/sources.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
@@ -12,8 +13,79 @@ void main() async {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();
   final features = PlatformFeatures.instance();
   final isAndroid = !kIsWeb && defaultTargetPlatform == TargetPlatform.android;
+  final isIOS = !kIsWeb && defaultTargetPlatform == TargetPlatform.iOS;
+  final isMacOS = !kIsWeb && defaultTargetPlatform == TargetPlatform.macOS;
   final audioTestDataList = await getAudioTestDataList();
 
+  testWidgets('test asset source with special char',
+      (WidgetTester tester) async {
+    final player = AudioPlayer();
+
+    await tester.pumpLinux();
+    await player.play(specialCharAssetTestData.source);
+    await tester.pumpAndSettle();
+    // Sources take some time to get initialized
+    await tester.pump(const Duration(seconds: 8));
+    await player.stop();
+
+    await tester.pumpLinux();
+    await player.dispose();
+  });
+
+  testWidgets(
+    'test device file source with special char',
+    (WidgetTester tester) async {
+      final player = AudioPlayer();
+
+      await tester.pumpLinux();
+      final path = await player.audioCache.loadPath(specialCharAsset);
+      expect(path, isNot(contains('%'))); // Ensure path is not URL encoded
+      await player.play(DeviceFileSource(path));
+      await tester.pumpAndSettle();
+      // Sources take some time to get initialized
+      await tester.pump(const Duration(seconds: 8));
+      await player.stop();
+
+      await tester.pumpLinux();
+      await player.dispose();
+    },
+    skip: kIsWeb,
+  );
+
+  testWidgets('test url source with special char', (WidgetTester tester) async {
+    final player = AudioPlayer();
+
+    await tester.pumpLinux();
+    await player.play(specialCharUrlTestData.source);
+    await tester.pumpAndSettle();
+    // Sources take some time to get initialized
+    await tester.pump(const Duration(seconds: 8));
+    await player.stop();
+
+    await tester.pumpLinux();
+    await player.dispose();
+  });
+
+  testWidgets(
+    'test url source with no extension',
+    (WidgetTester tester) async {
+      final player = AudioPlayer();
+
+      await tester.pumpLinux();
+      await player.play(noExtensionAssetTestData.source);
+      await tester.pumpAndSettle();
+      // Sources take some time to get initialized
+      await tester.pump(const Duration(seconds: 8));
+      await player.stop();
+
+      await tester.pumpLinux();
+      await player.dispose();
+    },
+    // Darwin does not support files without extension unless its specified
+    // #803, https://stackoverflow.com/a/54087143/5164462
+    skip: isIOS || isMacOS,
+  );
+
   group('play multiple sources', () {
     testWidgets(
       'play multiple sources simultaneously',

packages/audioplayers/example/assets/coins_non_ascii_и.wav

@@ -44,9 +44,8 @@ void main() async {
             testData: invalidAssetTestData,
           );
           fail('PlatformException not thrown');
-          // ignore: avoid_catches_without_on_clauses
-        } catch (e) {
-          expect(e, isInstanceOf<PlatformException>());
+        } on PlatformException catch (e) {
+          expect(e.message, startsWith('Failed to set source.'));
         }
         await tester.pumpLinux();
       },
@@ -64,8 +63,8 @@ void main() async {
           );
           fail('PlatformException not thrown');
           // ignore: avoid_catches_without_on_clauses
-        } catch (e) {
-          expect(e, isInstanceOf<PlatformException>());
+        } on PlatformException catch (e) {
+          expect(e.message, startsWith('Failed to set source.'));
         }
         await tester.pumpLinux();
       },
@@ -539,8 +538,8 @@ extension on WidgetTester {
     if (source is UrlSource) {
       await platform.setSourceUrl(playerId, source.url);
     } else if (source is AssetSource) {
-      final url = await AudioCache.instance.load(source.path);
-      await platform.setSourceUrl(playerId, url.path, isLocal: true);
+      final cachePath = await AudioCache.instance.loadPath(source.path);
+      await platform.setSourceUrl(playerId, cachePath, isLocal: true);
     } else if (source is BytesSource) {
       await platform.setSourceBytes(playerId, source.bytes);
     }

packages/audioplayers/example/integration_test/lib/lib_source_test_data.dart

@@ -18,6 +18,7 @@ final host = useLocalServer ? 'http://$localhost:8080' : 'https://luan.xyz';
 
 final wavUrl1 = '$host/files/audio/coins.wav';
 final wavUrl2 = '$host/files/audio/laser.wav';
+final wavUrl3 = '$host/files/audio/coins_non_ascii_и.wav';
 final mp3Url1 = '$host/files/audio/ambient_c_motion.mp3';
 final mp3Url2 = '$host/files/audio/nasa_on_a_mission.mp3';
 final m3u8StreamUrl = useLocalServer
@@ -30,6 +31,8 @@ final mpgaStreamUrl = useLocalServer
 const wavAsset = 'laser.wav';
 const mp3Asset = 'nasa_on_a_mission.mp3';
 const invalidAsset = 'invalid.txt';
+const specialCharAsset = 'coins_non_ascii_и.wav';
+const noExtensionAsset = 'coins_no_extension';
 
 class SourcesTab extends StatefulWidget {
   final AudioPlayer player;

packages/audioplayers/example/integration_test/lib_test.dart

@@ -68,8 +68,12 @@ <h1>Audioplayers Test Server</h1>
             href="https://pub.dev/packages/audioplayers">Audioplayers</a>
         package:</p>
     <ul>
-        <li><a href="/files/audio/laser.wav">/files/audio/ambient_c_motion.mp3</a></li>
+        <li><a href="/files/audio/ambient_c_motion.mp3">/files/audio/ambient_c_motion.mp3</a></li>
         <li><a href="/files/audio/coins.wav">/files/audio/coins.wav</a></li>
+        <li><a href="/files/audio/coins%20whitespace.wav">/files/audio/coins whitespace.wav</a></li>
+        <li><a href="/files/audio/coins_no_extension">/files/audio/coins_no_extension</a></li>
+        <li><a href="/files/audio/coins_non_ascii_%D0%B8.wav">/files/audio/coins_non_ascii_и.wav</a></li>
+        <li><a href="/files/audio/invalid.txt">/files/audio/invalid.txt</a></li>
         <li><a href="/files/audio/laser.wav">/files/audio/laser.wav</a></li>
         <li><a href="/files/audio/nasa_on_a_mission.mp3">/files/audio/nasa_on_a_mission.mp3</a></li>
         <li>

packages/audioplayers/example/integration_test/platform_test.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 
+import 'package:audioplayers/src/uri_ext.dart';
 import 'package:file/file.dart';
 import 'package:file/local.dart';
 import 'package:flutter/foundation.dart';
@@ -21,7 +22,7 @@ import 'package:path_provider/path_provider.dart';
 /// For most normal uses, the static instance is used. But if you want to
 /// control multiple caches, you can create your own instances.
 class AudioCache {
-  /// A globlally accessible instance used by default by all players.
+  /// A globally accessible instance used by default by all players.
   static AudioCache instance = AudioCache();
 
   @visibleForTesting
@@ -102,20 +103,35 @@ class AudioCache {
       return tryAbsolute!;
     }
 
-    // local asset
-    return Uri.parse('assets/$prefix$fileName');
+    // Relative Asset path
+    // URL-encode twice, see:
+    // https://github.com/flutter/engine/blob/2d39e672c95efc6c539d9b48b2cccc65df290cc4/lib/web_ui/lib/ui_web/src/ui_web/asset_manager.dart#L61
+    // Parsing an already encoded string to an Uri does not encode it a second
+    // time, so we have to do it manually:
+    final encoded = UriCoder.encodeOnce(fileName);
+    return Uri.parse(Uri.encodeFull('assets/$prefix$encoded'));
   }
 
   /// Loads a single [fileName] to the cache.
   ///
-  /// Also returns a [Future] to access that file.
+  /// Returns a [Uri] to access that file.
   Future<Uri> load(String fileName) async {
     if (!loadedFiles.containsKey(fileName)) {
       loadedFiles[fileName] = await fetchToMemory(fileName);
     }
     return loadedFiles[fileName]!;
   }
 
+  /// Loads a single [fileName] to the cache.
+  ///
+  /// Returns a decoded [String] to access that file.
+  Future<String> loadPath(String fileName) async {
+    final encodedPath = (await load(fileName)).path;
+    // Web needs an url double-encoded path.
+    // Darwin needs a decoded path for local files.
+    return kIsWeb ? encodedPath : Uri.decodeFull(encodedPath);
+  }
+
   /// Loads a single [fileName] to the cache but returns it as a File.
   ///
   /// Note: this is not available for web, as File doesn't make sense on the
@@ -125,8 +141,9 @@ class AudioCache {
       throw 'This method cannot be used on web!';
     }
     final uri = await load(fileName);
-    return fileSystem.file(uri.toFilePath(
-        windows: defaultTargetPlatform == TargetPlatform.windows));
+    return fileSystem.file(
+      uri.toFilePath(windows: defaultTargetPlatform == TargetPlatform.windows),
+    );
   }
 
   /// Loads a single [fileName] to the cache but returns it as a list of bytes.

packages/audioplayers/example/lib/tabs/sources.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:audioplayers/audioplayers.dart';
+import 'package:audioplayers/src/uri_ext.dart';
 import 'package:audioplayers_platform_interface/audioplayers_platform_interface.dart';
 import 'package:flutter/services.dart';
 import 'package:meta/meta.dart';
@@ -325,8 +326,13 @@ class AudioPlayer {
   Future<void> setSourceUrl(String url) async {
     _source = UrlSource(url);
     await creatingCompleter.future;
+    // Encode remote url to avoid unexpected failures.
     await _completePrepared(
-      () => _platform.setSourceUrl(playerId, url, isLocal: false),
+      () => _platform.setSourceUrl(
+        playerId,
+        UriCoder.encodeOnce(url),
+        isLocal: false,
+      ),
     );
   }
 
@@ -349,10 +355,10 @@ class AudioPlayer {
   /// this method.
   Future<void> setSourceAsset(String path) async {
     _source = AssetSource(path);
-    final url = await audioCache.load(path);
+    final cachePath = await audioCache.loadPath(path);
     await creatingCompleter.future;
     await _completePrepared(
-      () => _platform.setSourceUrl(playerId, url.path, isLocal: true),
+      () => _platform.setSourceUrl(playerId, cachePath, isLocal: true),
     );
   }