Overview
The Romanizer class provides Korean text romanization functionality using the koroman library. It converts Korean Hangul characters to Latin script (Romanized Korean).
Dependencies
This class requires the koroman library:
Import
from tagqt.core.roman import Romanizer
Methods
romanize_text
Converts Korean text to Romanized Latin characters.
@staticmethod
def romanize_text(text: str) -> str
The Korean text to romanize
ImportError if the koroman library is not installed
Example:
try:
result = Romanizer.romanize_text("방탄소년단")
print(result) # "bangtansonyeondan"
result = Romanizer.romanize_text("블랙핑크")
print(result) # "beullaegpingkeu"
except ImportError as e:
print(e) # "koroman library is not installed. Install with: pip install koroman"
from tagqt.core.tags import MetadataHandler
from tagqt.core.roman import Romanizer
try:
metadata = MetadataHandler("song.flac")
# Romanize Korean artist name
if metadata.artist:
romanized = Romanizer.romanize_text(metadata.artist)
print(f"Original: {metadata.artist}")
print(f"Romanized: {romanized}")
# Optionally update the metadata
metadata.artist = romanized
metadata.save()
except ImportError:
print("Please install koroman: pip install koroman")
Batch Processing Example
import os
from tagqt.core.tags import MetadataHandler
from tagqt.core.roman import Romanizer
def romanize_directory(directory):
"""Romanize all Korean text in metadata for files in directory."""
for filename in os.listdir(directory):
if filename.endswith(('.flac', '.mp3')):
filepath = os.path.join(directory, filename)
try:
metadata = MetadataHandler(filepath)
# Romanize artist
if metadata.artist:
metadata.artist = Romanizer.romanize_text(metadata.artist)
# Romanize album
if metadata.album:
metadata.album = Romanizer.romanize_text(metadata.album)
# Romanize title
if metadata.title:
metadata.title = Romanizer.romanize_text(metadata.title)
metadata.save()
print(f"Processed: {filename}")
except Exception as e:
print(f"Error processing {filename}: {e}")
# Usage
romanize_directory("/path/to/music")
Error Handling
The method handles errors gracefully:
- Missing dependency: Raises
ImportError with installation instructions
- Romanization errors: Returns the original text unchanged and prints an error message
- Empty input: Returns an empty string
try:
result = Romanizer.romanize_text("한글")
except ImportError as e:
print(f"Dependency missing: {e}")
# Handle missing dependency (e.g., prompt user to install)
Notes
- All methods are static and do not require instantiation
- The
koroman library must be installed separately
- Non-Korean text is passed through unchanged
- Romanization follows standard Korean romanization rules as implemented by
koroman
- If romanization fails for any reason, the original text is returned to prevent data loss
