# UltrastarParser
Contains methods to read or edit ultrastar files or directories.
## Installation
Use the package manager of your choice: [pypi](https://pypi.org/project/ultrastarParser/).
## 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](https://usdx.eu/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.
```ascii
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
```python
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
Raw data
{
"_id": null,
"home_page": "https://github.com/randompersona1/ultrastarParser",
"name": "ultrastarParser",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "ultrastar, parser, karaoke",
"author": "randompersona1",
"author_email": "74961116+randompersona1@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/8b/46/73fc74559adb8e019457d6ead83540342a699880236cf4d4ac6038d38d26/ultrastarparser-0.6.14.tar.gz",
"platform": null,
"description": "# UltrastarParser\n\nContains methods to read or edit ultrastar files or directories.\n\n## Installation\n\nUse the package manager of your choice: [pypi](https://pypi.org/project/ultrastarParser/).\n\n## Usage tips\n\n- 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.\n- 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](https://usdx.eu/format) they are compatible with, but this might not be correct.\n- 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.\n\n```ascii\nlibrary_folder/\n\u251c\u2500\u2500 song_1/\n\u2502 \u251c\u2500\u2500 song_1.txt\n\u2502 \u251c\u2500\u2500 song_1.mp3\n\u2502 \u2514\u2500\u2500 ...\n\u251c\u2500\u2500 song_2/\n\u2502 \u251c\u2500\u2500 song_2.txt\n\u2502 \u251c\u2500\u2500 song_2.m4a\n\u2502 \u251c\u2500\u2500 song_2 [CO].jpg\n\u2502 \u2514\u2500\u2500 ...\n\u2514\u2500\u2500 song_3/\n \u2514\u2500\u2500 ...\n```\n\n## Features\n\n```python\nfrom ultrastarparser import Song, Library\n\n\nsong = Song('path_to_txt_file')\nsong.get_attribute('ARTIST') # Returns song artist\nsong.set_attribute('ARTIST', 'Bon Jovi') # Set song artist\nsong.set_version('1.1.0') # Set song file version. See https://usdx.eu/format.\nsong.flush() # Flush changes made to the file system. \n\n\nlib = Library('path_to_library')\nfor s in lib:\n # check for somthing in every song\nsongs_by_bon_jovi = lib.search('ARTIST', 'Bon Jovi') # Returns all songs with Bon Jovi as artist\nlib.export('export_path', 'json') # exports library to path as certain format. \n```\n\n## Planned features\n\n- Many more docstrings\n- Ability to backup files, for example before overwriting\n- Logging\n- Better error handling (and documentation of error handling)\n- Metadata extraction not from txt file (e.g. song duration from audio file or video resolution from video file)\n\n## Unplanned features\n\n- Editing the songtext and notes\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parser for Ultrastar text files.",
"version": "0.6.14",
"project_urls": {
"Homepage": "https://github.com/randompersona1/ultrastarParser"
},
"split_keywords": [
"ultrastar",
" parser",
" karaoke"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c2f95f35d897f2f8fbad82670c0728252e68671947c51e8ec5ecca875ba49da",
"md5": "b2f0258a8e0b13e3ca941d6d589fb36e",
"sha256": "d19d59dab25960d316f4801e28b2b8058d2aa4fef24e35c4bbed4fc3e3d06844"
},
"downloads": -1,
"filename": "ultrastarparser-0.6.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b2f0258a8e0b13e3ca941d6d589fb36e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 10881,
"upload_time": "2025-01-16T03:03:01",
"upload_time_iso_8601": "2025-01-16T03:03:01.041691Z",
"url": "https://files.pythonhosted.org/packages/5c/2f/95f35d897f2f8fbad82670c0728252e68671947c51e8ec5ecca875ba49da/ultrastarparser-0.6.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b4673fc74559adb8e019457d6ead83540342a699880236cf4d4ac6038d38d26",
"md5": "94ed2b80a1dffdcc0fb345ceb48fc80e",
"sha256": "61ac3f8054a64ca91358f35be3c02860dd22a9f722d50ca6f951e2e015ec1fb8"
},
"downloads": -1,
"filename": "ultrastarparser-0.6.14.tar.gz",
"has_sig": false,
"md5_digest": "94ed2b80a1dffdcc0fb345ceb48fc80e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 9433,
"upload_time": "2025-01-16T03:03:04",
"upload_time_iso_8601": "2025-01-16T03:03:04.579894Z",
"url": "https://files.pythonhosted.org/packages/8b/46/73fc74559adb8e019457d6ead83540342a699880236cf4d4ac6038d38d26/ultrastarparser-0.6.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 03:03:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "randompersona1",
"github_project": "ultrastarParser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ultrastarparser"
}
JSON
