UltrastarParser

Contains methods to read or edit ultrastar files or directories.

Installation

Use the package manager of your choice: pypi.

Usage tips

• Make a backup of the text files. The library currently does not touch any other files. Though I try very hard to fix bugs and use the library myself, I cannot guarantee your files won't go up in flames, particularly if you are using a non-standard file structure or encoding. If something does go wrong, please file an issue.
• Methods will delete information. For example, comments interlaced with the attributes will not be saved and subsequently overwritten when writing. Changing the version of a song doesn't technically remove information, but could result in your program not being able to parse the file. Programs should disclose what version of the ultrastar file format they are compatible with, but this might not be correct.
• Ultrastar libraries should be structured like below. Not following this will probably still work, but is not recommended and could cause issues in the future.

library_folder/
├── song_1/
│   ├── song_1.txt
│   ├── song_1.mp3
│   └── ...
├── song_2/
│   ├── song_2.txt
│   ├── song_2.m4a
│   ├── song_2 [CO].jpg
│   └── ...
└── song_3/
    └── ...

Features

from ultrastarparser import Song, Library


song = Song('path_to_txt_file')
song.get_attribute('ARTIST') # Returns song artist
song.set_attribute('ARTIST', 'Bon Jovi') # Set song artist
song.set_version('1.1.0') # Set song file version. See https://usdx.eu/format.
song.flush() # Flush changes made to the file system. 


lib = Library('path_to_library')
for s in lib:
    # check for somthing in every song
songs_by_bon_jovi = lib.search('ARTIST', 'Bon Jovi') # Returns all songs with Bon Jovi as artist
lib.export('export_path', 'json') # exports library to path as certain format. 

Planned features

• Many more docstrings
• Ability to backup files, for example before overwriting
• Logging
• Better error handling (and documentation of error handling)
• Metadata extraction not from txt file (e.g. song duration from audio file or video resolution from video file)

Unplanned features

• Editing the songtext and notes