Platform Notes

Platform-specific considerations and optimizations for hAudiotagger.

Overview

hAudiotagger provides a consistent API across all platforms. However, there are some platform-specific behaviors and optimizations to be aware of.

Android

Permissions

No special permissions are required for reading/writing audio metadata. hAudiotagger uses the app's storage access.

Performance

• File path API — Best performance. Rust reads files directly.
• Bytes API — Slightly slower due to data transfer across FFI.
• Batch operations — Use file path API for maximum throughput.

Storage Access Framework

If you're using SAF (Storage Access Framework) to pick files, you'll need to read the file bytes first:

final file = await FilePicker.platform.pickFiles();
final bytes = await File(file!.files.first.path!).readAsBytes();
final tag = await Haudiotagger.readFromBytes(bytes);

iOS

Permissions

No special permissions required for metadata access.

iTunes Metadata

iOS uses iTunes-style metadata (ilst). hAudiotagger fully supports reading and writing iTunes metadata fields.

Performance

Similar to Android — file path API is faster than bytes API.

Linux

Performance

Linux gets the best performance due to:

• Direct file system access
• Rayon parallelism for batch operations
• No sandbox restrictions

Dependencies

No system dependencies required. hAudiotagger bundles its own native libraries.

macOS

Performance

Similar to Linux with full rayon parallelism support.

App Sandbox

If your app uses App Sandbox, ensure you have the appropriate entitlements for file access:

<key>com.apple.security.files.user-selected.read-write</key>
<true/>

Windows

Performance

Full performance with rayon parallelism.

File Paths

Use forward slashes or escaped backslashes:

// Correct
await Haudiotagger.read('C:/Music/song.mp3');
await Haudiotagger.read('C:\\Music\\song.mp3');

Web

Limitations

• No file path API — Use *FromBytes variants only
• Single-threaded — No rayon parallelism
• WASM required — Must enable cross-origin isolation

Performance

Web is slower than native due to:

• WASM overhead
• Data serialization across FFI
• Single-threaded execution

For large batch operations, consider using native platforms.

File Access

Users must select files via file picker:

final result = await FilePicker.platform.pickFiles(type: FileType.audio);
final bytes = result.files.first.bytes;
final tag = await Haudiotagger.readFromBytes(bytes!);

See Web Setup for detailed configuration.

Performance Comparison

Operation	Native (100 files)	Web (100 files)
Read	1,282 f/s	~77 f/s
Write	197 f/s	~30 f/s
Update	197 f/s	~20 f/s

f/s = files per second

Best Practices

1. Use file path API on native — Always prefer file path over bytes on native platforms
2. Use bytes API on web — File paths are not available on web
3. Batch operations — Use batchWrite or batchUpdate for multiple files
4. Read field when possible — Use readField instead of read when you only need one value
5. Preview before write — Use pipeline preview to see changes before applying

---