# 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/e9/02/0ced6b390b22ddd6534cf15d5fcc67181eed9cbf8957052e3846ec770d61/ultrastarparser-0.6.13.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.13",
"project_urls": {
"Homepage": "https://github.com/randompersona1/ultrastarParser"
},
"split_keywords": [
"ultrastar",
" parser",
" karaoke"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2d02924b8592f0d7318f7e9c1d0da6e0487dbe10e86494954b51a68a26339d8d",
"md5": "3a58893b5e91c3ea5b5b9dcbeae14fd8",
"sha256": "1a5f763625e66f7dd787452924e345b60d10f15984c40dd1383a886d30b50180"
},
"downloads": -1,
"filename": "ultrastarparser-0.6.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a58893b5e91c3ea5b5b9dcbeae14fd8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 10850,
"upload_time": "2024-08-13T18:55:29",
"upload_time_iso_8601": "2024-08-13T18:55:29.903463Z",
"url": "https://files.pythonhosted.org/packages/2d/02/924b8592f0d7318f7e9c1d0da6e0487dbe10e86494954b51a68a26339d8d/ultrastarparser-0.6.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9020ced6b390b22ddd6534cf15d5fcc67181eed9cbf8957052e3846ec770d61",
"md5": "69083502d40b12881b556563c986d1e8",
"sha256": "3be959460e74a632033fb7c3820a0c90c4c4879cff00ea01c5f9d6b883959d20"
},
"downloads": -1,
"filename": "ultrastarparser-0.6.13.tar.gz",
"has_sig": false,
"md5_digest": "69083502d40b12881b556563c986d1e8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 9809,
"upload_time": "2024-08-13T18:55:31",
"upload_time_iso_8601": "2024-08-13T18:55:31.327572Z",
"url": "https://files.pythonhosted.org/packages/e9/02/0ced6b390b22ddd6534cf15d5fcc67181eed9cbf8957052e3846ec770d61/ultrastarparser-0.6.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 18:55:31",
"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
