CSV Import/Export

​

Overview

• Export metadata from your audio files to CSV format
• Edit metadata in spreadsheet applications (Excel, LibreOffice Calc, Google Sheets)
• Import the modified metadata back into your audio files

​

CSV Structure

​

Column Layout

​

Field Names

# From csv_io.py:9-10
fieldnames = ['filepath', 'filename', 'title', 'artist', 'album', 
              'album_artist', 'year', 'genre', 'disc_number', 
              'track_number', 'bpm', 'initial_key', 'comment', 'lyrics']

​

Exporting Metadata

​

Export Process

1. Navigate to File → Export to CSV
2. Choose a location and filename
3. Click Save
4. All files in the current library will be exported

​

Export Implementation

def export_metadata_to_csv(files_data, filepath):
    fieldnames = ['filepath', 'filename', 'title', 'artist', ...]
    
    with open(filepath, 'w', newline='', encoding='utf-8') as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        
        for path, meta in files_data:
            row = {
                'filepath': path,
                'filename': os.path.basename(path),
                'title': meta.title or '',
                'artist': meta.artist or '',
                # ... more fields
            }
            writer.writerow(row)

​

Example Export

filepath,filename,title,artist,album,album_artist,year,genre,disc_number,track_number,bpm,initial_key,comment,lyrics
/music/song1.mp3,song1.mp3,Song Title,Artist Name,Album Name,Album Artist,2024,Rock,1,01,120,Am,Great track,First line...
/music/song2.flac,song2.flac,Another Song,Different Artist,Album 2,,2023,Pop,,02,128,C,,[Verse 1]...

​

Importing Metadata

​

Import Process

1. Edit the exported CSV file in your spreadsheet application
2. Save the changes
3. In TagQt, navigate to File → Import from CSV
4. Select the modified CSV file
5. Review the import progress in the batch status dialog

​

Import Implementation

# From csv_io.py:40-46
def import_metadata_from_csv(filepath):
    with open(filepath, 'r', encoding='utf-8') as f:
        reader = csv.DictReader(f)
        return list(reader), None

​

File Matching

​

Editing CSV Files

​

Spreadsheet Applications

• Microsoft Excel: Open the CSV file directly
• LibreOffice Calc: Use “Text CSV” import
• Google Sheets: Import the CSV file
• Text Editors: Any text editor (VS Code, Notepad++, etc.)

​

Common Editing Tasks

​

Bulk Editing

1. Standardize artist names: Use find/replace to fix variations
2. Fix album names: Correct spelling or capitalization
3. Add missing genres: Fill in genre information for multiple tracks
4. Update years: Correct release years for albums
5. Renumber tracks: Use spreadsheet formulas to generate track numbers

​

Formula Examples (Excel/LibreOffice)

# Generate track numbers with padding
=TEXT(ROW()-1, "00")

# Combine artist and title
=B2 & " - " & C2

# Extract year from date
=YEAR(G2)

# Uppercase genre
=UPPER(H2)

​

Field Handling

​

Empty Fields

• During export: Missing metadata is exported as empty
• During import: Empty fields are set to empty strings (clearing existing data)

​

Special Characters

• Unicode characters (émojis, accented characters, etc.)
• Multi-line text in the lyrics field
• Commas and quotes (automatically escaped by the CSV library)

​

Lyrics Field

• Multi-line text (preserved with line breaks)
• LRC timestamps
• Special characters

​

Batch Import Status

• Real-time progress: Progress bar showing completion percentage
• Individual file status: Success/error status for each file
• Error reporting: Detailed error messages for failed imports
• Batch summary: Total successes, failures, and skipped files

​

Import Results

​

Best Practices

​

Export

1. Export before editing: Always export first to get the current state
2. Use descriptive filenames: Include date in export filename (e.g., metadata-2024-03-04.csv)
3. Test on a small subset: Export a few files first to understand the format

​

Import

1. Keep filepath column unchanged: Don’t modify the filepath column
2. Verify paths: Ensure all file paths in the CSV are valid
3. Test on copies: Test import on backup files first
4. Check encoding: Save CSV files with UTF-8 encoding
5. Preserve quotes: Let your spreadsheet application handle special characters

​

Workflow

1. Export metadata to CSV
2. Create a backup copy of the CSV file
3. Edit the CSV in your spreadsheet application
4. Save the CSV (UTF-8 encoding)
5. Create backups of your audio files (optional but recommended)
6. Import the modified CSV
7. Verify the changes in TagQt
8. Save changes to audio files

​

Error Handling

​

Export Errors

• No files to export: Load files before exporting
• Permission denied: Check write permissions for the export location
• Disk full: Ensure adequate disk space

​

Import Errors

• File not found: CSV references files that don’t exist
• Invalid CSV format: CSV file is corrupted or improperly formatted
• Encoding issues: CSV not saved with UTF-8 encoding
• Permission denied: Can’t write to audio files (check permissions)

​

Technical Details

​

Source Code Reference

• Source: tagqt/core/csv_io.py
• Functions:
  • export_metadata_to_csv(files_data, filepath) - Export to CSV
  • import_metadata_from_csv(filepath) - Read CSV data
• Worker: CsvImportWorker (in tagqt/ui/workers.py)

​

CSV Library

• csv.DictWriter for exports (writes rows as dictionaries)
• csv.DictReader for imports (reads rows as dictionaries)
• Automatic handling of quotes and escaping
• UTF-8 encoding support

​

Use Cases

​

Album Metadata Correction

1. Export metadata to CSV
2. In spreadsheet:
   • Sort by album
   • Update album artist
   • Set disc numbers
   • Fix track numbering
3. Import back to TagQt

​

Genre Classification

1. Export to CSV
2. Use spreadsheet pivot tables and filtering
3. Assign genres based on artist or album patterns
4. Use formulas to batch-assign genres
5. Import updated metadata

​

Metadata Cleanup

1. Export to CSV
2. Use find/replace for common issues:
   • Remove extra spaces
   • Standardize capitalization
   • Fix encoding errors
3. Import cleaned data