Tag Editor - Documentation

1. Overview

The Tag Editor in SonicSyncSail allows users to modify metadata associated with their local audio files directly from within the application. This includes editing fields such as the song title, album, artist, genre, and—most notably—updating the album artwork through an integrated image picker. The feature is designed to provide full local control over a user’s media library, allowing them to maintain accurate metadata, correct inconsistencies, or personalize their music collection.

Tag editing is executed entirely on-device. No external servers or cloud-based metadata systems are involved. This ensures privacy, speed, and reliability, especially for users who maintain large offline libraries.

2. Purpose and User Value

• Correcting inconsistent metadata for downloaded or transferred audio files.
• Personalizing the listening experience through custom artwork or updated song details.
• Improving library organization across sorting, grouping, and searching features.
• Ensuring consistent display across the player UI, notifications, PulseSync, and dynamic queues.

By offering complete local editing, SonicSyncSail becomes a full music management tool rather than just a playback app.

3. Technical Architecture

3.1 MediaStore Integration

SonicSyncSail uses Android’s MediaStore APIs to update metadata fields directly in the device’s media database. Supported metadata fields include title, album, artist, genre, and album art.

3.2 Room Database Interactions

• Fast media lookups
• Improved dynamic queue construction
• Tracking of user-modified artwork

3.3 FileProvider Integration

Secure access to user-selected images via FileProvider ensures compatibility with modern Android security models.

3.4 Image Picker and Artwork Processing

• System Photo Picker / SAF
• PNG/JPEG conversion
• Temporary artwork caching

3.5 Permissions

• READ_MEDIA_IMAGES
• READ_MEDIA_AUDIO
• WRITE_MEDIA_AUDIO
• READ_EXTERNAL_STORAGE (legacy)

4. User Interface & Experience

4.1 Editable Fields

• Song Title
• Album
• Artist
• Genre
• Track Number
• Album Art (Image Picker & Web Search)

4.2 Album Art Selection

Users can select artwork from:

• Local image picker
• Built-in web search browser

4.3.1 Image Picker Workflow

1. User taps the artwork area.
2. Photo picker / SAF opens.
3. Image previewed instantly.
4. Saved to MediaStore or embedded in file.

4.3.2 Web Search Artwork Workflow

A built-in browser allows searching for album covers. Long-pressing an image downloads and loads it directly.

4.3.3 Unified Saving Pipeline

All images undergo the same validation, compression, and embedding steps for consistent behavior.

4.4 Commit Changes Flow

• Metadata is updated through MediaStore.
• Artwork is saved and indexed.
• Room DB updates immediately.
• MediaSession refreshes without restarting playback.

5. Internal Implementation Details

5.1 Metadata Writing

• MediaStore operations
• ID3 tag editing (MP3)
• External artwork fallback

5.2 Artwork Storage Logic

• Embed when supported
• Fallback for AAC/FLAC formats
• Remove outdated artwork references

5.3 Consistency Synchronization

• Artwork cache refresh
• Notification metadata update
• Live playback sync

5.4 Failure Handling

• Read-only file protection
• Image validation + compression
• SAF fallback for legacy devices

6. Edge Cases and Safeguards

6.1 Read-Only Files

Editor prevents modifications and informs the user.

6.2 Unsupported Formats

Artwork stored externally via MediaStore.

6.3 Missing Permissions

UI remains disabled until permission is granted.

6.4 Corrupted/Large Images

Auto-compression and error messages ensure stable behavior.