Skip to content

sok.file_operations.music_operations

File operations for music media.

This module handles:

  • Detection and extraction of information from audio file names
  • Reading metadata (ID3, FLAC tags, etc.)
  • Automatic track renaming
  • Organization by artist/album

MusicFileOperations

class MusicFileOperations

Bases: FileOperations, FileParsingMixin, FileValidationMixin, FileListOrganizerMixin

File operations for music files.

Provides methods to extract metadata from audio filenames, read embedded tags (ID3, FLAC), organize by artist/album, and rename tracks according to music conventions.

Source

supported_extensionsproperty

List[str]

Return list of supported audio file extensions.

batch_target

def batch_target(
media_item: MediaItem,
file_path: Path,
alone: bool,
) -> Tuple[List[str], str]:

Folders and file name of a track of a batch.

When the service gives no track number, the number of the file tags is used if the file is on the same album.

Parameters

NameTypeDescription
media_itemMediaItem
file_pathPath
alonebool
Source

extract_info_from_filename

def extract_info_from_filename(filename: str) -> Dict[str, Any]:

Extract information from a audio filename.

The input patterns of the settings are tried first (sok.core.name_patterns); the name is otherwise read by the rules of _parse_filename. "pattern" is the pattern that matched, if any.

Parameters

NameTypeDescription
filenamestrFile name to parse.

Returns

  • Dict[str, Any]Dictionary with extracted information.
Source

find_audio_files

def find_audio_files(directory: str, recursive: bool = True) -> List[str]:

Find all audio files in a directory.

Parameters

NameTypeDefaultDescription
directorystrDirectory to scan.
recursiveboolTrueEnable recursive search.

Returns

  • List[str]List of audio file paths.
Source

find_files

def find_files(directory: str, recursive: bool = True) -> List[str]:

Unified alias for find_audio_files.

Parameters

NameTypeDefaultDescription
directorystr
recursiveboolTrue
Source

format_track

def format_track(
track: Any,
extension: str,
track_number: Optional[int] = None,
) -> List[str]:

Folders and file name of a track, from the music format setting.

The format, "{artist} - {album}/{track} - {title}" by default, has one part per folder and the file name last. A value the track does not have is left out with its separator: without a track number, "{track} - {title}" gives "Title".

Parameters

NameTypeDefaultDescription
trackAnyThe Track found online.
extensionstrExtension of the file, with its dot.
track_numberOptional[int]NoneNumber to use when the track has none.

Returns

  • List[str]The folder names, then the file name.
Source

generate_new_filename

def generate_new_filename(
media_item: Optional[MediaItem],
original_filename: str,
) -> str:

Generate a new filename for an audio track.

For a track found online, the file part of the music format of the settings (see format_track). Otherwise, from the original name: '01 - Track Title.mp3'.

Parameters

NameTypeDescription
media_itemOptional[MediaItem]The media item (Album or Track).
original_filenamestrOriginal filename.

Returns

  • strNew filename.
Source

organize_by_artist_album

def organize_by_artist_album(
source_path: str,
dest_path: str,
use_metadata: bool = True,
dry_run: bool = False,
) -> Dict[str, Any]:

Organize audio files by Artist/Album.

Created structure: Artist/Album (Year)/tracks

Parameters

NameTypeDefaultDescription
source_pathstrSource folder.
dest_pathstrDestination folder.
use_metadataboolTrueUse file metadata.
dry_runboolFalseSimulation mode.

Returns

  • Dict[str, Any]Organization report.
Source

read_metadata

def read_metadata(file_path: str) -> Dict[str, Any]:

Read metadata from an audio file.

Reads ID3, FLAC tags, and other embedded metadata.

Parameters

NameTypeDescription
file_pathstrAudio file path.

Returns

  • Dict[str, Any]Dictionary with read metadata.
Source

Attributes

NameValue
loggerlogging.getLogger(__name__)
Built with Kiln