Skip to main content
Namida includes a comprehensive tag editor powered by native platform extractors, allowing you to modify audio file metadata without leaving the app.

​
Editing Track Metadata

​
Supported Tag Fields

The tag editor supports a wide range of metadata fields:

Basic Info

  • Title
  • Artist
  • Album
  • Album Artist
  • Composer

Organization

  • Track Number
  • Track Total
  • Disc Number
  • Disc Total
  • Year

Classification

  • Genre
  • Mood
  • Tags
  • Rating
  • Language

​
Additional Fields

  • Lyrics: Full lyric text (supports synced .lrc import)
  • Comment: General comments or notes
  • Description: Detailed track description
  • Synopsis: Brief summary
  • Remixer: Remix artist information
  • Lyricist: Lyric author
  • Record Label: Publishing label
  • Country: Country of origin
Customize how tracks appear in sorted lists:
  • Title Sort
  • Album Sort
  • Album Artist Sort
  • Artist Sort
  • Composer Sort
These fields don’t change display names but affect alphabetical ordering.

​
Batch Editing

​
Edit Multiple Tracks

Apply changes to multiple files simultaneously: 
await updateTracksMetadata(
  tracks: selectedTracks,
  editedTags: {
    TagField.genre: 'Electronic',
    TagField.year: '2024',
    TagField.albumArtist: 'Various Artists',
  },
  trimWhiteSpaces: true,
);
1

Select Tracks

Use Namida’s global track selection to choose multiple tracks across different views (albums, artists, playlists).
2

Open Tag Editor

Long-press on selected tracks and choose “Edit Tags” from the context menu.
3

Modify Fields

Enter new values for the fields you want to change. Leave fields empty to preserve existing values.
4

Apply Changes

Confirm to write changes to all selected files simultaneously.
Batch editing preserves unique values. For example, editing the artist field on multiple tracks won’t overwrite their individual titles.

​
Artwork Management

​
Embedding Album Art

Add or replace embedded artwork in audio files: 
await updateTracksMetadata(
  tracks: tracks,
  editedTags: {},
  imagePath: '/storage/music/cover.jpg',
);

Supported Formats

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • BMP (.bmp)

Recommendations

  • Size: 500x500 to 1000x1000 pixels
  • Format: JPEG for best compatibility
  • Quality: 85-95% compression
Embedding large images (>5MB) may increase file size significantly and cause compatibility issues with some players.

​
Extract Artwork

Extract embedded artwork from audio files: 
FArtwork? artwork = await extractArtwork(
  trackPath: track.path,
  isVideo: track is Video,
);

if (artwork.file != null) {
  // Save or use the extracted artwork
  await artwork.file.copy(destinationPath);
}

​
Rating System

Namida supports a percentage-based rating system (0-100): 
// Set rating to 80%
await updateTracksMetadata(
  tracks: [track],
  editedTags: {
    TagField.rating: '80',
  },
);
Ratings are stored in the file’s metadata and also maintained in Namida’s track statistics database.

​
Comment Insertion

Add timestamped comments to track history: 
// Insert comment (appends to existing comments)
await updateTracksMetadata(
  tracks: [track],
  editedTags: {},
  commentToInsert: 'Downloaded from YouTube: video_id',
);
Use cases:
  • YouTube video ID tracking
  • Download source attribution
  • Personal notes and reminders
  • Timestamp markers

​
Advanced Features

​
Whitespace Trimming

Automatically clean up metadata by removing extra whitespace: 
await updateTracksMetadata(
  tracks: tracks,
  editedTags: editedTags,
  trimWhiteSpaces: true, // Removes leading/trailing spaces
);

​
Preserve File Dates

Maintain original file creation and modification timestamps: 
// Keep original file dates after editing
await file.executeAndKeepStats(
  () async {
    // Perform tag editing operations
  },
  keepStats: settings.editTagsKeepFileDates.value,
);
When enabled:
  • Original creation date preserved
  • Original modification date preserved
  • Access time updated normally
Enable in: Settings → Tags → Keep File Dates

​
Track Statistics Integration

Some fields are stored separately in Namida’s statistics database:

Mood

Comma-separated mood tags

Tags

Custom classification tags

Rating

0-100 percentage rating
// Update both file tags AND statistics
await Indexer.inst.updateTrackStats(
  track,
  ratingString: '85',
  tagsString: 'favorites, workout, energy',
  moodsString: 'happy, energetic',
);

​
Network Track Handling

For network-sourced tracks (streaming, remote servers), only statistics fields (mood, tags, rating) can be edited. File-based tags cannot be modified.
if (track.isNetwork) {
  // Only update statistics, not file tags
  final newStats = await Indexer.inst.updateTrackStats(track, ...);
  // Error: "Not Supported for network files"
}

​
Error Handling

​
Common Issues

Error: file not foundCauses:
  • Track file was moved or deleted
  • SD card unmounted
  • Insufficient permissions
Solution: Verify file location or refresh library
Error: Requires MANAGE_EXTERNAL_STORAGE permissionSolution:
  1. Navigate to Settings → Permissions
  2. Grant “All Files Access” permission
  3. Restart the app if needed
Possible causes:
  • Corrupted file header
  • Unsupported audio format
  • File is in use by another app
  • Read-only file system
Troubleshooting:
  1. Close other music apps
  2. Check file permissions
  3. Try editing a single field first
  4. Copy file to internal storage and retry

​
Callbacks & Progress

Track tag editing progress with callbacks: 
await updateTracksMetadata(
  tracks: tracks,
  editedTags: editedTags,
  onEdit: (didUpdate, error, track) {
    if (didUpdate) {
      print('✓ Updated: ${track.title}');
    } else {
      print('✗ Failed: ${track.title} - $error');
    }
  },
  onUpdatingTracksStart: () {
    // All file operations complete
    // Now updating internal library
  },
  onStatsEdit: (newStats) {
    // Statistics database updated
  },
);

​
Library Reindexing

After editing tags, Namida automatically reindexes affected tracks:
1

Write Tags to File

Tag data is written to the audio file using platform-native extractors.
2

Update Track Maps

Internal track database is updated with new metadata.
3

Rebuild Media Lists

Albums, artists, genres, and other media lists are regenerated.
4

Refresh UI

All views displaying the edited tracks are automatically refreshed.
The entire process is atomic - if tag writing fails, the library is not modified.

​
Best Practices

Before Editing

  • Backup important files
  • Close other music apps
  • Ensure sufficient storage
  • Verify file permissions

During Editing

  • Use consistent formatting
  • Enable whitespace trimming
  • Add specific genre/mood tags
  • Include year information

​
Format Compatibility

  • MP3 (.mp3) - ID3v2 tags
  • M4A/MP4 (.m4a, .mp4) - iTunes tags
  • FLAC (.flac) - Vorbis comments
  • OGG (.ogg) - Vorbis comments
  • OPUS (.opus) - Vorbis comments
  • WMA (.wma) - Windows Media tags
  • WAV (.wav) - Basic ID3 tags
  • APE (.ape) - APEv2 tags
  • WV (.wv) - APEv2 tags
Some formats have limited tag field support. Test with a single file first.

​
Tag Extraction Settings

Configure extraction behavior in Settings:
  • Artist Separators: Customize how multi-artist tracks are split
  • Genre Separators: Configure genre delimiter characters
  • Extract Feat. Artists: Auto-detect featured artists in titles
  • Keep File Dates: Preserve timestamps after editing
  • Trim Whitespace: Auto-clean metadata strings

Build docs developers (and LLMs) love

Get started for freeTalk to us