Skip to main content
This guide will walk you through the basic workflow of using TagQt to edit audio file metadata.

​
Prerequisites

Before you begin, make sure you have installed TagQt and have some audio files ready to edit.

​
Basic workflow

1

Launch TagQt

Open a terminal, navigate to the TagQt directory, and run the application:
cd /path/to/tagqt
source venv/bin/activate  # if using virtual environment
python main.py
The main window will appear with three main sections:
  • Header - Title, filter box, and progress indicators
  • File list - Left panel showing your audio files in a table
  • Sidebar - Right panel for editing metadata and cover art
You can resize the panels by dragging the divider between them.
2

Open a folder

Load your audio files by opening a folder:Using the menu:
  1. Click File → Open Folder…
  2. Browse to your music folder
  3. Click Select Folder
Using keyboard shortcut: Press Ctrl+O to open the folder dialogTagQt will scan the folder and load all supported audio files (MP3, FLAC, OGG, M4A, WAV). A progress indicator will show the loading status.
TagQt scans all files recursively in the selected folder and its subfolders.
3

Select and view a file

Once your files are loaded:
  1. Click on any file in the file list
  2. The sidebar will populate with the file’s current metadata:
    • Cover art (if available)
    • Basic fields: Title, Artist, Album, Album Artist, Year, Genre
    • Show More button to access extended fields
Extended metadata fields (click Show More):
  • Disc number
  • Track number
  • BPM (beats per minute)
  • Key (musical key)
  • ISRC (International Standard Recording Code)
  • Label (publisher)
  • Comment
  • Lyrics (expandable text editor)
Use the filter box at the top of the file list to quickly find files by name, title, artist, or album.
4

Edit metadata

To edit a single file:
  1. Select a file from the list
  2. Modify any field in the sidebar:
    • Type directly into text fields
    • Click Show More to access additional fields
    • Edit lyrics in the expandable text editor
  3. Press Ctrl+S or click the Save button at the bottom of the sidebar
Example edit:
Title: My Song
Artist: The Artist
Album: Greatest Hits
Year: 2024
Genre: Rock
Changes are not written to the file until you click Save or press Ctrl+S.

​
Global edit mode

To edit multiple files at once:
  1. Select multiple files:
    • Hold Ctrl and click individual files
    • Hold Shift to select a range
    • Press Ctrl+A to select all visible files
  2. The sidebar switches to Global Edit Mode
  3. Edit any fields you want to change
  4. Empty fields are left unchanged - only filled fields are applied
  5. Click Save to apply changes to all selected files
Global Edit Mode applies changes to ALL selected files. Empty fields will not overwrite existing values.
To exit Global Edit Mode, press Escape or select a single file.
5

Manage cover art

TagQt provides several ways to work with cover art:

​
View current cover

The cover art appears at the top of the sidebar. The resolution is displayed below the image.

​
Fetch cover online

  1. Select one or more files
  2. Click Get Cover in the sidebar, or
  3. Use Tools → Covers → Get Covers (All Visible)
TagQt will search for album artwork online and embed it in your files.

​
Load from file

  1. Click Load Cover in the sidebar
  2. Select an image file (JPG, PNG, etc.)
  3. The image is automatically resized and embedded

​
Click to view

Click on the cover art in the sidebar to search for new covers online.
Cover art is automatically resized to 500×500 pixels to keep file sizes manageable.

​
Advanced features

​
Auto-tagging with MusicBrainz

Automatically fetch metadata from MusicBrainz:
  1. Select files to auto-tag
  2. Go to Edit → Auto-Tag → Selected (or All Visible)
  3. Choose whether to skip files that already have tags
  4. Watch the progress bar as TagQt queries MusicBrainz
Example from main.py
from tagqt.core.musicbrainz import MusicBrainzClient

# Auto-tag worker queries MusicBrainz for each file
worker = AutoTagWorker(files, skip_existing=True)

​
Batch rename files

Rename files based on metadata patterns:
  1. Select files to rename
  2. Go to Tools → File Actions → Rename Files (Selected)
  3. Preview the new filenames in the dialog
  4. Click Rename to apply
The renamer uses metadata templates to generate consistent filenames.

​
Fetch lyrics

Automatically fetch lyrics for your tracks:
  1. Select one or more files
  2. Click Get Lyrics in the sidebar, or
  3. Use Tools → Lyrics → Get Lyrics (All Visible)
TagQt will fetch synchronized lyrics and embed them in your files. Load lyrics from file:
  1. Click Load Lyrics in the sidebar
  2. Select a .lrc or text file
  3. Lyrics are loaded into the editor

​
Case conversion

Standardize the case of metadata fields:
  1. Select files
  2. Go to Edit → Case Conversion
  3. Choose:
    • Title Case - Capitalizes First Letter Of Each Word
    • UPPERCASE - CONVERTS EVERYTHING TO UPPERCASE
    • lowercase - converts everything to lowercase

​
View modes

Organize your file list by different criteria:
  • File - Simple flat list
  • Album - Group by album name
  • Artist - Group by artist
  • Album Artist - Group by album artist
Access view modes from View → View By.

​
Command palette

Press Ctrl+K to open the command palette for quick access to all features: 
Available commands:
- Open Folder (Ctrl+O)
- Save Changes (Ctrl+S)
- Get Covers (All)
- Get Lyrics (All)
- Rename Files
- Auto-Tag (All)
- Re-encode FLAC
- Toggle Theme
- Exit Global Edit (Escape)

​
Import/Export CSV

Batch import or export metadata using CSV files: Export:
  1. File → Export to CSV
  2. Choose a location
  3. All loaded files are exported with their metadata
Import:
  1. File → Import from CSV
  2. Select your CSV file
  3. Metadata is applied to matching files

​
Keyboard shortcuts

Speed up your workflow with these shortcuts:
ShortcutAction
Ctrl+OOpen folder
Ctrl+SSave changes
Ctrl+GToggle global edit
Ctrl+KOpen command palette
Ctrl+ASelect all files
EscapeExit global edit mode
Ctrl+QQuit application

​
Tips and best practices

When tagging an album, use Global Edit Mode to set common fields like Album, Album Artist, and Year for all tracks at once. Then edit track-specific fields like Title and Track Number individually.
Use the filter box to narrow down your file list before performing batch operations like auto-tag or rename. This helps you work on specific subsets of your collection.
TagQt doesn’t auto-save changes. Remember to press Ctrl+S after editing to write changes to disk.
For batch operations, click the progress bar to view detailed status information for each file.
In Global Edit Mode, leaving a field empty means “don’t change this field” rather than “clear this field.” This allows you to update only specific fields across multiple files.

​
Next steps

Now that you know the basics, explore more advanced features:
  • FLAC re-encoding - Optimize FLAC files with different compression levels
  • Lyrics romanization - Convert Korean lyrics to romanized text using Koroman
  • Custom workflows - Combine filters, view modes, and batch operations for efficient tagging
For more information about specific features, use the built-in help system: Help → Hints & Tips or Keyboard Shortcuts.

Build docs developers (and LLMs) love

Get started for freeTalk to us