| Name | sng-parser JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | |
| Summary | Python library for reading .sng files |
| upload_time | 2024-02-18 23:01:37 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2024 Josh Mcdaniel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
sng
.sng
clone hero
ch
file
sng-format
sng-parse
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sng-format-python
-----------------------
Python implementation for parsing and handling .sng files. [See the .sng format spec for information](https://github.com/mdsitton/SngFileFormat/tree/main).
It is capable of reading SNG files, extracting metadata, encoding audio to .opus file indexes, and file data.
I have not tested this end-to-end, but I've had zero issues with it so far.
# Instalation
## From pip
``` shell
pip install sng-parser
```
## From repository
``` shell
git clone https://github.com/joshrmcdaniel/sng-format-python.git
cd sng-format-python
pip install -e .
```
# Usage
``` console
foo@bar:~$ sng_parser -h
usage:
sng_parser encode [-h] [-o path/to/encoded.sng] [-i] [-f] [-V sng_version] [-e] song_dir
sng_parser decode [-h] [-o path/to/out/folder] [-i] [-d relative/to/out_dir] [-f] sng_file
Decode/encode sng files
options:
-h, --help show this help message and exit
-v Logging level to use, more log info is shown by adding more `v`'s
action:
Encode to or decode from an sng file. For futher usage, run sng_parser {encode|decode} -h
{encode|decode}
foo@bar:~$ sng_parser encode -h
usage: sng_parser encode [-h] [-o path/to/encoded.sng] [-i] [-f] [-V sng_version] [-e] song_dir
positional arguments:
song_dir Directory to encode in the sng format
options:
-h, --help show this help message and exit
-o path/to/encoded.sng, --out-file path/to/encoded.sng
The output path of the SNG file. Defaults to the md5 sum of the containing files of the target dir.
-i, --ignore-nonsng-files
Allow encoding of files not allowed by the sng standard. Default: True.
-f, --force Overwrite existing files or directories. Default: False.
-V sng_version, --version sng_version
sng format version to use.
-e, --encode-audio Encode the audio files to opus. Default: False.
foo@bar:~$ sng_parser decode -h
usage: sng_parser decode [-h] [-o path/to/out/folder] [-i] [-d relative/to/out_dir] [-f] sng_file
positional arguments:
sng_file Directory to encode in the sng format
options:
-h, --help show this help message and exit
-o path/to/out/folder, --out-dir path/to/out/folder
The output directory of sng file's directory. Default: /your/working/dir (current working dir)
-i, --ignore-nonsng-files
Allow decoding of files not allowed by the sng standard. Default: True
-d relative/to/out_dir, --sng-dir relative/to/out_dir
The output directory containing the decoded sng file contents. Generated from metadata if not specified
-f, --force Overwrite existing files or directories. Defaults: False
```
The only functions a user should use for deconding and encoding is `decode_sng`, and `encode_sng`. The other functions are internal helpers.
`decode_sng` takes the following arguments:
- Keyword or passed arg:
- `sng_file`: os.PathLike | str | BufferedReader
- Can be the path to the sng file to parse, or a buffer
- Keyword only:
- `outdir`: Optional[os.PathLike | str]
- Output directory to write the song file to, defaults to the working directory
- `allow_nonsng_files`: bool
- Allow files encoded not specified by the sng stardard to be decoded, defaults to `False`
- `sng_dir`: Optional[os.PathLike | str]
- Directory containing the decoded files when writing to `outdir`, generated from metadata if not specified (`<artist_name> - <song_name> (<charter>)`)
- `overwrite` : bool
- Overwrite the existing directory if it already exists, defaults to `False`
`encode_sng` takes the following arguments:
- Keyword or passed arg:
- `dir_to_encode (os.PathLike)`: The directory containing files to be encoded into the SNG format
- Keyword only:
- `output_filename`: Optional[os.PathLike]
- The path to the output SNG file. Defaults to the md5 sum of the containing files of converted dir.
- `allow_nonsng_files`: Optional[bool]
- Allow encoding of files not allowed by the sng standard. Defaults to `False`.
- `overwrite`: Optional[bool]
- If `True`, existing files or directories will be overwritten. Defaults to `False`.
- `version`: Optional[int]
- The version of the SNG format to use. Defaults to `1`.
- `xor_mask`: Optional[bytes]
- XOR mask for encryption. If not provided, a random one is generated.
- `metadata`: Optional[SngMetadataInfo]:
- Metadata for the SNG package. If not provided, it's read from a 'song.ini' file in the directory.
## Example usage
```python
from sng_parser import decode_sng, encode_sng
outdir = 'test'
# Basic usage
## Decoding
decode_sng('example.sng', sng_dir=outdir)
## Encoding
encode_sng(outdir)
# Decode to `/name` with contents under `jeff` (sng files located in /name/jeff/)
decode_sng('example.sng', outdir='/name', sng_dir='jeff')
# Decode with file handler
with open('example.sng', 'rb') as f:
decode_sng(f)
# Decode ignoring non-standard .sng files
decode_sng('example.sng', allow_nonsng_files=True)
# Encode ignoring non-standard .sng files
encode_sng(outdir, allow_nonsng_files=True)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "sng-parser",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "sng,.sng,clone hero,ch,file,sng-format,sng-parse",
"author": "",
"author_email": "Josh Mcdaniel <80354972+joshrmcdaniel@users.noreply.github.com>",
"download_url": "",
"platform": null,
"description": "# sng-format-python\n-----------------------\nPython implementation for parsing and handling .sng files. [See the .sng format spec for information](https://github.com/mdsitton/SngFileFormat/tree/main).\n\nIt is capable of reading SNG files, extracting metadata, encoding audio to .opus file indexes, and file data.\n\nI have not tested this end-to-end, but I've had zero issues with it so far.\n\n# Instalation\n## From pip\n``` shell\npip install sng-parser\n```\n\n## From repository\n``` shell\ngit clone https://github.com/joshrmcdaniel/sng-format-python.git\ncd sng-format-python\npip install -e .\n```\n\n# Usage\n\n``` console\nfoo@bar:~$ sng_parser -h\nusage: \nsng_parser encode [-h] [-o path/to/encoded.sng] [-i] [-f] [-V sng_version] [-e] song_dir\nsng_parser decode [-h] [-o path/to/out/folder] [-i] [-d relative/to/out_dir] [-f] sng_file\n\nDecode/encode sng files\n\noptions:\n -h, --help show this help message and exit\n -v Logging level to use, more log info is shown by adding more `v`'s\n\naction:\n Encode to or decode from an sng file. For futher usage, run sng_parser {encode|decode} -h\n\n {encode|decode}\n\nfoo@bar:~$ sng_parser encode -h\nusage: sng_parser encode [-h] [-o path/to/encoded.sng] [-i] [-f] [-V sng_version] [-e] song_dir\n\npositional arguments:\n song_dir Directory to encode in the sng format\n\noptions:\n -h, --help show this help message and exit\n -o path/to/encoded.sng, --out-file path/to/encoded.sng\n The output path of the SNG file. Defaults to the md5 sum of the containing files of the target dir.\n -i, --ignore-nonsng-files\n Allow encoding of files not allowed by the sng standard. Default: True.\n -f, --force Overwrite existing files or directories. Default: False.\n -V sng_version, --version sng_version\n sng format version to use.\n -e, --encode-audio Encode the audio files to opus. Default: False.\nfoo@bar:~$ sng_parser decode -h\nusage: sng_parser decode [-h] [-o path/to/out/folder] [-i] [-d relative/to/out_dir] [-f] sng_file\n\npositional arguments:\n sng_file Directory to encode in the sng format\n\noptions:\n -h, --help show this help message and exit\n -o path/to/out/folder, --out-dir path/to/out/folder\n The output directory of sng file's directory. Default: /your/working/dir (current working dir)\n -i, --ignore-nonsng-files\n Allow decoding of files not allowed by the sng standard. Default: True\n -d relative/to/out_dir, --sng-dir relative/to/out_dir\n The output directory containing the decoded sng file contents. Generated from metadata if not specified\n -f, --force Overwrite existing files or directories. Defaults: False\n\n```\n\nThe only functions a user should use for deconding and encoding is `decode_sng`, and `encode_sng`. The other functions are internal helpers.\n\n`decode_sng` takes the following arguments:\n- Keyword or passed arg:\n - `sng_file`: os.PathLike | str | BufferedReader\n - Can be the path to the sng file to parse, or a buffer\n- Keyword only:\n - `outdir`: Optional[os.PathLike | str]\n - Output directory to write the song file to, defaults to the working directory\n - `allow_nonsng_files`: bool\n - Allow files encoded not specified by the sng stardard to be decoded, defaults to `False`\n - `sng_dir`: Optional[os.PathLike | str]\n - Directory containing the decoded files when writing to `outdir`, generated from metadata if not specified (`<artist_name> - <song_name> (<charter>)`)\n - `overwrite` : bool\n - Overwrite the existing directory if it already exists, defaults to `False`\n\n`encode_sng` takes the following arguments:\n- Keyword or passed arg:\n - `dir_to_encode (os.PathLike)`: The directory containing files to be encoded into the SNG format\n- Keyword only:\n - `output_filename`: Optional[os.PathLike]\n - The path to the output SNG file. Defaults to the md5 sum of the containing files of converted dir.\n - `allow_nonsng_files`: Optional[bool]\n - Allow encoding of files not allowed by the sng standard. Defaults to `False`.\n - `overwrite`: Optional[bool]\n - If `True`, existing files or directories will be overwritten. Defaults to `False`.\n - `version`: Optional[int]\n - The version of the SNG format to use. Defaults to `1`.\n - `xor_mask`: Optional[bytes]\n - XOR mask for encryption. If not provided, a random one is generated.\n - `metadata`: Optional[SngMetadataInfo]: \n - Metadata for the SNG package. If not provided, it's read from a 'song.ini' file in the directory.\n\n## Example usage\n\n```python\n\nfrom sng_parser import decode_sng, encode_sng\n\noutdir = 'test'\n# Basic usage\n## Decoding\ndecode_sng('example.sng', sng_dir=outdir)\n\n## Encoding\nencode_sng(outdir)\n\n# Decode to `/name` with contents under `jeff` (sng files located in /name/jeff/)\ndecode_sng('example.sng', outdir='/name', sng_dir='jeff')\n\n# Decode with file handler\nwith open('example.sng', 'rb') as f:\n decode_sng(f)\n\n# Decode ignoring non-standard .sng files\ndecode_sng('example.sng', allow_nonsng_files=True)\n\n# Encode ignoring non-standard .sng files\nencode_sng(outdir, allow_nonsng_files=True)\n\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Josh Mcdaniel Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Python library for reading .sng files",
"version": "1.3.0",
"project_urls": {
"homepage": "https://github.com/joshrmcdaniel/sng-format-python"
},
"split_keywords": [
"sng",
".sng",
"clone hero",
"ch",
"file",
"sng-format",
"sng-parse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "282ed151772cc4db534e170a0ec542de4d9e9b66522515d9fa21c4c827799dc6",
"md5": "c95366955746fdf5a0d86b99e852d320",
"sha256": "7e1fa8ef07883f5fc4cab6e92e016cc468b2043e0106a5379e69bfb0ee0fcfaf"
},
"downloads": -1,
"filename": "sng_parser-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c95366955746fdf5a0d86b99e852d320",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18720,
"upload_time": "2024-02-18T23:01:37",
"upload_time_iso_8601": "2024-02-18T23:01:37.222115Z",
"url": "https://files.pythonhosted.org/packages/28/2e/d151772cc4db534e170a0ec542de4d9e9b66522515d9fa21c4c827799dc6/sng_parser-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-18 23:01:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joshrmcdaniel",
"github_project": "sng-format-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sng-parser"
}
