Files
stemengine_old/backend/services_root_backup/metadata_util.py
T
2026-03-03 14:52:19 +09:00

558 lines
19 KiB
Python
Executable File

"""
Audio metadata (ID3 / Vorbis / EXIF) utilities for reading and writing tags.
Uses mutagen for format-agnostic read/write.
"""
from pathlib import Path
from typing import Optional, List, Dict, Tuple
import re
def _read_cover_art(source_path: str):
"""
Read cover art from an audio file.
Returns (data_bytes, mime_type) or (None, None) if not found.
"""
try:
ext = Path(source_path).suffix.lower()
if ext == '.mp3':
from mutagen.id3 import ID3, ID3NoHeaderError
try:
tags = ID3(source_path)
apic_keys = [k for k in tags.keys() if k.startswith('APIC')]
if apic_keys:
apic = tags[apic_keys[0]]
return apic.data, apic.mime
except ID3NoHeaderError:
pass
elif ext == '.flac':
from mutagen.flac import FLAC
audio = FLAC(source_path)
if audio.pictures:
pic = audio.pictures[0]
return pic.data, pic.mime
elif ext == '.wav':
from mutagen.wave import WAVE
try:
audio = WAVE(source_path)
if audio.tags:
apic_keys = [k for k in audio.tags.keys() if k.startswith('APIC')]
if apic_keys:
apic = audio.tags[apic_keys[0]]
return apic.data, apic.mime
except Exception:
pass
except Exception:
pass
return None, None
def copy_metadata(source_path: str, dest_path: str, stem_label: Optional[str] = None,
copy_lyrics: bool = True) -> None:
"""
Copy all common tags (title, artist, album, track, date, genre, cover art, lyrics)
from source_path to dest_path. Optionally appends stem_label to the title.
Silently ignores unsupported formats — metadata is cosmetic, never fatal.
"""
try:
import mutagen
src = mutagen.File(source_path, easy=True)
if src is None:
return
title = src.get("title", [""])[0] if src.get("title") else ""
artist = src.get("artist", [""])[0] if src.get("artist") else ""
album = src.get("album", [""])[0] if src.get("album") else ""
tracknumber = src.get("tracknumber", [""])[0] if src.get("tracknumber") else ""
date = src.get("date", [""])[0] if src.get("date") else ""
genre = src.get("genre", [""])[0] if src.get("genre") else ""
if stem_label and title:
title = f"{title} ({stem_label})"
elif stem_label:
title = stem_label
cover_data, cover_mime = _read_cover_art(source_path)
# Read lyrics from source
lyrics = ""
if copy_lyrics:
lyrics = _read_lyrics_from_file(source_path)
ext = Path(dest_path).suffix.lower()
if ext == ".mp3":
_write_mp3_tags(dest_path, title, artist, album, tracknumber, date, genre,
cover_data, cover_mime, lyrics)
elif ext == ".flac":
_write_flac_tags(dest_path, title, artist, album, tracknumber, date, genre,
cover_data, cover_mime, lyrics)
elif ext == ".wav":
_write_wav_tags(dest_path, title, artist, album, tracknumber, date, genre,
cover_data, cover_mime)
except Exception:
pass # Never fail over metadata — it's cosmetic
def _read_lyrics_from_file(path: str) -> str:
"""Read lyrics from a file using the same logic as read_metadata."""
try:
ext = Path(path).suffix.lower()
if ext == '.mp3':
return _read_mp3_lyrics(path)
elif ext in ('.flac', '.ogg', '.opus'):
return _read_vorbis_lyrics(path)
except Exception:
pass
return ''
def _write_mp3_tags(path, title, artist, album, tracknumber, date, genre,
cover_data=None, cover_mime=None, lyrics=None):
from mutagen.id3 import ID3, ID3NoHeaderError, TIT2, TPE1, TALB, TRCK, TDRC, TCON, APIC, USLT
try:
tags = ID3(path)
except ID3NoHeaderError:
tags = ID3()
if title: tags["TIT2"] = TIT2(encoding=3, text=title)
if artist: tags["TPE1"] = TPE1(encoding=3, text=artist)
if album: tags["TALB"] = TALB(encoding=3, text=album)
if tracknumber: tags["TRCK"] = TRCK(encoding=3, text=tracknumber)
if date: tags["TDRC"] = TDRC(encoding=3, text=date)
if genre: tags["TCON"] = TCON(encoding=3, text=genre)
if lyrics: tags["USLT::'eng'"] = USLT(encoding=3, lang='eng', desc='', text=lyrics)
if cover_data:
tags["APIC:"] = APIC(
encoding=3, mime=cover_mime or "image/jpeg",
type=3, desc="Cover", data=cover_data,
)
tags.save(path)
def _write_flac_tags(path, title, artist, album, tracknumber, date, genre,
cover_data=None, cover_mime=None, lyrics=None):
from mutagen.flac import FLAC, Picture
audio = FLAC(path)
if title: audio["title"] = title
if artist: audio["artist"] = artist
if album: audio["album"] = album
if tracknumber: audio["tracknumber"] = tracknumber
if date: audio["date"] = date
if genre: audio["genre"] = genre
if lyrics: audio["lyrics"] = lyrics
if cover_data:
pic = Picture()
pic.type = 3 # front cover
pic.mime = cover_mime or "image/jpeg"
pic.desc = "Cover"
pic.data = cover_data
audio.clear_pictures()
audio.add_picture(pic)
audio.save()
def _write_wav_tags(path, title, artist, album, tracknumber, date, genre,
cover_data=None, cover_mime=None):
from mutagen.wave import WAVE
from mutagen.id3 import TIT2, TPE1, TALB, TRCK, TDRC, TCON, APIC
try:
audio = WAVE(path)
if audio.tags is None:
audio.add_tags()
if title: audio.tags["TIT2"] = TIT2(encoding=3, text=title)
if artist: audio.tags["TPE1"] = TPE1(encoding=3, text=artist)
if album: audio.tags["TALB"] = TALB(encoding=3, text=album)
if tracknumber: audio.tags["TRCK"] = TRCK(encoding=3, text=tracknumber)
if date: audio.tags["TDRC"] = TDRC(encoding=3, text=date)
if genre: audio.tags["TCON"] = TCON(encoding=3, text=genre)
if cover_data:
audio.tags["APIC:"] = APIC(
encoding=3, mime=cover_mime or "image/jpeg",
type=3, desc="Cover", data=cover_data,
)
audio.save()
except Exception:
pass
# ---------------------------------------------------------------------------
# Metadata reading
# ---------------------------------------------------------------------------
def read_metadata(source_path: str) -> dict:
"""
Read basic metadata from an audio file.
Returns dict with 'artist', 'title', 'album', 'lyrics' keys (all str).
Lyrics are read in order of priority:
1. Synced lyrics tags (SYLT for MP3, syncedlyrics for FLAC/OGG)
2. Unsynced lyrics tags (USLT for MP3, lyrics/unsyncedlyrics for FLAC/OGG)
3. External .lrc file with same base name
Silently returns empty strings on failure or unsupported format.
"""
result = {'artist': '', 'title': '', 'album': '', 'lyrics': ''}
try:
import mutagen
src = mutagen.File(source_path, easy=True)
if src is None:
return result
result['artist'] = (src.get('artist') or [''])[0]
result['title'] = (src.get('title') or [''])[0]
result['album'] = (src.get('album') or [''])[0]
ext = Path(source_path).suffix.lower()
lyrics = ''
# Try to read lyrics from tags first
if ext == '.mp3':
lyrics = _read_mp3_lyrics(source_path)
elif ext in ('.flac', '.ogg', '.opus'):
lyrics = _read_vorbis_lyrics(source_path)
# If no lyrics in tags, try external LRC file
if not lyrics:
lyrics = read_lrc_file(source_path)
result['lyrics'] = lyrics
except Exception:
pass
return result
def _read_mp3_lyrics(path: str) -> str:
"""Read lyrics from ID3 tags: SYLT (synced) → USLT (unsynced) → TXXX:LYRICS.
Also checks $-prefixed variants used by some tagging software.
"""
try:
from mutagen.id3 import ID3, ID3NoHeaderError
try:
tags = ID3(path)
except ID3NoHeaderError:
return ''
# Synced lyrics: SYLT contains list of (text, time_ms) tuples
sylt_keys = [k for k in tags.keys() if k.startswith('SYLT')]
if sylt_keys:
return '\n'.join(t for t, _ in tags[sylt_keys[0]].text)
# Unsynced lyrics
uslt_keys = [k for k in tags.keys() if k.startswith('USLT')]
if uslt_keys:
return tags[uslt_keys[0]].text
# TXXX:LYRICS fallback (also check $-prefixed variants)
for txxx_key in ('TXXX:LYRICS', 'TXXX:$LYRICS',
'TXXX:SYNCEDLYRICS', 'TXXX:$SYNCEDLYRICS',
'TXXX:UNSYNCEDLYRICS', 'TXXX:$UNSYNCEDLYRICS'):
if txxx_key in tags:
text = tags[txxx_key].text
if text:
return text[0] if isinstance(text, list) else str(text)
except Exception:
pass
return ''
def _read_vorbis_lyrics(path: str) -> str:
"""Read lyrics from FLAC/OGG Vorbis comment tags.
Checks SYNCEDLYRICS, LYRICS, and UNSYNCEDLYRICS (case-insensitive).
Also checks variants with $ prefix (e.g., $LYRICS) used by some tagging software.
Returns the first non-empty value found, or empty string if all are empty.
"""
try:
import mutagen
f = mutagen.File(path)
if f is None:
return ''
# Build case-insensitive lookup: upper() -> original key
key_map = {k.upper(): k for k in f.keys()}
# Check in priority order: SYNCEDLYRICS -> LYRICS -> UNSYNCEDLYRICS
# Also check $-prefixed variants as fallback
for key in ('SYNCEDLYRICS', '$SYNCEDLYRICS',
'LYRICS', '$LYRICS',
'UNSYNCEDLYRICS', '$UNSYNCEDLYRICS'):
if key in key_map:
val = f.get(key_map[key])
if val:
return val[0]
except Exception:
pass
return ''
# ---------------------------------------------------------------------------
# LRC file utilities
# ---------------------------------------------------------------------------
LRC_LINE_REGEX = re.compile(
r'^(\[\s*(\d+):(\d{1,2})(?:\.(\d{1,3}))?\s*\])' # timestamp [mm:ss.xx]
r'\s*(.*?)$', # lyrics text
re.MULTILINE
)
ELRC_WORD_REGEX = re.compile(
r'(<\s*(\d+):(\d{1,2})(?:\.(\d{1,3}))?\s*>)' # word timestamp <mm:ss.xx>
r'\s*([^<\n]+)', # word text
re.MULTILINE
)
def read_lrc_file(audio_path: str) -> str:
"""
Read lyrics from an external .lrc file with the same base name as the audio file.
Returns the raw LRC content or empty string if not found.
"""
audio_path = Path(audio_path)
lrc_path = audio_path.with_suffix('.lrc')
if not lrc_path.exists():
# Try case-insensitive search (covers both .lrc and .LRC on Linux)
for pattern in ('*.lrc', '*.LRC'):
for f in audio_path.parent.glob(pattern):
if f.stem.lower() == audio_path.stem.lower():
lrc_path = f
break
if lrc_path.exists():
break
if lrc_path.exists():
try:
return lrc_path.read_text(encoding='utf-8', errors='ignore')
except Exception:
pass
return ''
def parse_lrc(lrc_content: str) -> List[Tuple[float, str]]:
"""
Parse LRC content into list of (timestamp_seconds, line_text) tuples.
Args:
lrc_content: Raw LRC file content
Returns:
List of (timestamp, line) tuples sorted by timestamp
"""
lines = []
for match in LRC_LINE_REGEX.finditer(lrc_content):
minutes = int(match.group(2))
seconds = int(match.group(3))
millis = match.group(4)
text = match.group(5).strip()
if millis:
# Handle different millisecond precisions
millis = int(millis.ljust(3, '0')[:3])
else:
millis = 0
timestamp = minutes * 60 + seconds + millis / 1000.0
if text:
lines.append((timestamp, text))
# Sort by timestamp and remove duplicates
lines.sort(key=lambda x: x[0])
# Remove duplicate timestamps (keep first occurrence)
seen = set()
unique_lines = []
for ts, text in lines:
if ts not in seen:
seen.add(ts)
unique_lines.append((ts, text))
return unique_lines
def parse_elrc(elrc_content: str) -> List[Tuple[float, str, List[Tuple[float, str]]]]:
"""
Parse Enhanced LRC (ELRC) content with word-level timestamps.
Args:
elrc_content: Raw ELRC file content
Returns:
List of (line_timestamp, line_text, [(word_timestamp, word), ...]) tuples
"""
lines = []
for match in LRC_LINE_REGEX.finditer(elrc_content):
minutes = int(match.group(2))
seconds = int(match.group(3))
millis = match.group(4)
full_line = match.group(5)
if millis:
millis = int(millis.ljust(3, '0')[:3])
else:
millis = 0
line_timestamp = minutes * 60 + seconds + millis / 1000.0
# Parse word-level timestamps within this line
words = []
for word_match in ELRC_WORD_REGEX.finditer(full_line):
w_minutes = int(word_match.group(2))
w_seconds = int(word_match.group(3))
w_millis = word_match.group(4)
w_text = word_match.group(5).strip()
if w_millis:
w_millis = int(w_millis.ljust(3, '0')[:3])
else:
w_millis = 0
word_timestamp = w_minutes * 60 + w_seconds + w_millis / 1000.0
if w_text:
words.append((word_timestamp, w_text))
# Clean line text (remove word timestamps)
line_text = ELRC_WORD_REGEX.sub(r'\5', full_line).strip()
if line_text or words:
lines.append((line_timestamp, line_text, words))
lines.sort(key=lambda x: x[0])
return lines
def format_lrc(lines: List[Tuple[float, str]], include_empty: bool = False) -> str:
"""
Format lines back into LRC format.
Args:
lines: List of (timestamp_seconds, line_text) tuples
include_empty: Whether to include empty lines
Returns:
LRC formatted string
"""
result = []
for timestamp, text in lines:
if not text and not include_empty:
continue
minutes = int(timestamp // 60)
seconds = int(timestamp % 60)
millis = int((timestamp % 1) * 100)
result.append(f"[{minutes:02d}:{seconds:02d}.{millis:02d}]{text}")
return '\n'.join(result)
def format_elrc(lines: List[Tuple[float, str, List[Tuple[float, str]]]]) -> str:
"""
Format lines with word-level timestamps into ELRC format.
Args:
lines: List of (line_timestamp, line_text, [(word_timestamp, word), ...]) tuples
Returns:
ELRC formatted string
"""
result = []
for line_ts, line_text, words in lines:
minutes = int(line_ts // 60)
seconds = int(line_ts % 60)
millis = int((line_ts % 1) * 100)
if words:
# Build line with word timestamps
word_parts = []
for word_ts, word in words:
w_min = int(word_ts // 60)
w_sec = int(word_ts % 60)
w_mil = int((word_ts % 1) * 100)
word_parts.append(f"<{w_min:02d}:{w_sec:02d}.{w_mil:02d}>{word}")
line_content = ' '.join(word_parts)
else:
line_content = line_text
result.append(f"[{minutes:02d}:{seconds:02d}.{millis:02d}]{line_content}")
return '\n'.join(result)
def lyrics_to_plaintext(lyrics: str) -> str:
"""
Convert LRC/ELRC content to plain text (remove all timestamps).
Args:
lyrics: LRC formatted content
Returns:
Plain text lyrics
"""
# Remove line timestamps [mm:ss.xx]
text = re.sub(r'\[\s*\d+:\d{2}(?:\.\d{1,3})?\s*\]', '', lyrics)
# Remove word timestamps <mm:ss.xx>
text = re.sub(r'<\s*\d+:\d{2}(?:\.\d{1,3})?\s*>', '', text)
# Clean up whitespace
lines = [line.strip() for line in text.split('\n') if line.strip()]
return '\n'.join(lines)
def is_lrc_synced(lyrics: str) -> bool:
"""
Check if lyrics content contains LRC timestamps (synced lyrics).
Args:
lyrics: Lyrics content to check
Returns:
True if content contains LRC timestamps
"""
return bool(LRC_LINE_REGEX.search(lyrics))
def extract_lyrics_from_file(file_path: str) -> Dict[str, str]:
"""
Extract lyrics from an audio file or LRC file.
Args:
file_path: Path to audio file or LRC file
Returns:
Dict with 'source', 'raw', 'synced', 'plain' keys
- source: 'tag', 'lrc_file', or 'none'
- raw: Original lyrics content with timestamps if present
- synced: True if lyrics are timestamped
- plain: Plain text version without timestamps
"""
path = Path(file_path)
result = {'source': 'none', 'raw': '', 'synced': False, 'plain': ''}
# If it's an LRC file, read it directly
if path.suffix.lower() == '.lrc':
try:
content = path.read_text(encoding='utf-8', errors='ignore')
result['source'] = 'lrc_file'
result['raw'] = content
result['synced'] = is_lrc_synced(content)
result['plain'] = lyrics_to_plaintext(content)
except Exception:
pass
return result
# Otherwise, try to read from audio file metadata
metadata = read_metadata(file_path)
lyrics = metadata.get('lyrics', '')
if lyrics:
result['source'] = 'tag'
result['raw'] = lyrics
result['synced'] = is_lrc_synced(lyrics)
result['plain'] = lyrics_to_plaintext(lyrics)
else:
# Try external LRC file as last resort
lrc_content = read_lrc_file(file_path)
if lrc_content:
result['source'] = 'lrc_file'
result['raw'] = lrc_content
result['synced'] = is_lrc_synced(lrc_content)
result['plain'] = lyrics_to_plaintext(lrc_content)
return result