| Name | acoustic-solo-dadaGP JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Guitar tablature tokenization and processing toolkit. |
| upload_time | 2025-10-10 20:21:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2020 Dadabots
Copyright (c) 2025 Austin Liu and Ziyang Hu
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 |
music
guitar
tablature
tokenization
audio
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
PyGuitarPro
pytest
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# acoustic-solo-dadaGP
A modification of [DadaGP](https://github.com/dada-bots/dadaGP) tailored for **acoustic solo guitar** workflows. It supports alternative string tunings and multi‑track acoustic/clean guitar parts, with a simple CLI and a small public Python API.
---
## Table of Contents
1. [Background & Attribution](#background--attribution)
2. [What’s Changed](#whats-changed)
3. [Features](#features)
4. [Installation](#installation)
5. [Quick Start](#quick-start)
6. [CLI Reference](#cli-reference)
7. [Python Reference](#python-reference)
8. [Contributing](#contributing)
9. [License](#license)
---
## Background & Attribution
This project is a **fork** of [`dada-bots/dadaGP`](https://github.com/dada-bots/dadaGP). Credit to the original authors for the foundational GP↔︎token pipeline.
---
## What’s Changed
- **Enhanced Acoustic Support** — optimized defaults and checks for acoustic/clean guitar usage.
- **Compatibility with pyguitarpro** — works with `pyguitarpro>=0.9`.
- **Alternative Tunings** — supports non‑standard tunings (drop D, Celtic, etc.).
- **Multi‑track Handling** — process up to 3 acoustic/clean tracks; optional merge‑down to one.
- **Refined CLI** — ergonomic `asdadagp` tool for encode/decode/process/info.
- **Token Utilities** — helpers for measure splitting, repeats/alternatives, and tuning extraction.
---
## Features
- Convert `.gp3/.gp4/.gp5/.gpx` ⇆ token text files
- Optional **track merge**: keep only the first acoustic/clean track and strip `cleanX:` prefixes
- **Measure & repeat analysis** helpers (playing order, measure objects)
- Basic **file validation / info** summaries
- Small **Python API** for scripting
---
## Installation
### From PyPI (recommended)
```bash
pip install acoustic-solo-dadaGP
```
### From source
```bash
git clone https://github.com/austinliu05/acoustic-solo-dadaGP.git
cd acoustic-solo-dadaGP
pip install -e .
```
Python >=3.8 is required.
---
## Quick Start
```bash
# Encode a Guitar Pro file to tokens
asdadagp encode song.gp5 tokens.txt --artist "John Doe"
# Decode tokens back to Guitar Pro
asdadagp decode tokens.txt song_out.gp5
# Process tokens: merge to single acoustic track
asdadagp process tokens.txt processed.txt --merge-tracks
# Process tokens with structured measures JSON (includes tuning & playing order)
asdadagp process tokens.txt processed.json --merge-tracks --measures
# Inspect file info (works for both .gp* or token files)
asdadagp info song.gp5
asdadagp info tokens.txt
```
---
## CLI Reference
The package installs the `asdadagp` command.
### `encode` — Guitar Pro → tokens
```
asdadagp encode INPUT.gp[3|4|5|x] OUTPUT.txt [--artist NAME] [--tuning]
```
- `INPUT.gp*` — Guitar Pro file to encode
- `OUTPUT.txt` — destination token file (one token per line)
- `--artist NAME` — optional first‑line artist token (default: `"Unknown"`)
- `--tuning` — if set, append tuning info to note tokens; otherwise only string tunings in the header
### `decode` — tokens → Guitar Pro
```
asdadagp decode INPUT.txt OUTPUT.gp5
```
- `INPUT.txt` — token file produced by `encode`/processing
- `OUTPUT.gp5` — Guitar Pro output (GP5 format is typical target)
### `process` — transform token streams
```
asdadagp process INPUT.txt OUTPUT.(txt|json) [--merge-tracks] [--measures]
```
- `--merge-tracks` — Merge all tracks into 1 (otherwise it keeps only the first acoustic/clean guitar track) and
remove `cleanX:` prefixes (e.g., `clean0:note:s6:f0:D3 → note:s6:f0:D3`)
- `--measures` — output a **JSON** object with:
- `tokens` — index→token map (all processed tokens)
- `measures` — list of per‑measure token lists
- `playing_order` — measure indices in actual playback order accounting for repeats/alternatives
- `tuning` — string tuning extracted from tokens
> If `--measures` is used, `OUTPUT` **must** end with `.json`.
### `info` — summarize a file
```
asdadagp info INPUT.(gp3|gp4|gp5|gpx|txt)
```
- For `.gp*` files: prints title/artist/album/track count/measure count/tempo + per‑track tunings
- For token files: prints token counts and rough token‑type histogram
---
## Python Reference
Import from the top‑level package `asdadagp`:
```python
from asdadagp import (
__version__,
# main conversions
asdadagp_encode, guitarpro2tokens,
asdadagp_decode, tokens2guitarpro,
# processing helpers
get_string_tunings, tracks_check, tokens_to_measures, measures_playing_order,
# utilities
get_tuning_type, get_fret, convert_spn_to_common,
# constants
instrument_groups, supported_times, wait_token_list2,
)
```
### Conversions
#### `asdadagp_encode(input_file: str, output_file: str, note_tuning: bool, artist_token: str) -> None`
Encodes a Guitar Pro file into a token text file.
- **input_file**: path to `.gp3/.gp4/.gp5/.gpx` file
- **output_file**: path to write tokens (one per line)
- **note_tuning**: if `True`, append tuning to note tokens
- **artist_token**: first‑line artist token (e.g., `"John Doe"`)
Related lower‑level function:
#### `guitarpro2tokens(song: guitarpro.Song, artist: str, verbose: bool, note_tuning: bool) -> list[str]`
Converts an in‑memory `guitarpro.Song` into tokens.
#### `asdadagp_decode(input_file: str, output_file: str) -> None`
Decodes a token text file back into a Guitar Pro file.
Related lower‑level function:
#### `tokens2guitarpro(all_tokens: list[str], verbose: bool = False) -> guitarpro.Song`
Builds an in‑memory `guitarpro.Song` from tokens.
### Processing
#### `get_string_tunings(tokens: list[str]) -> list[str]`
Extracts per‑string tunings from a token list.
#### `tracks_check(tokens: list[str], merge_track: bool) -> list[str]`
Optionally merges to the first acoustic/clean track and removes `cleanX:` prefixes.
#### `tokens_to_measures(tokens: list[str]) -> list[TokenMeasure]`
Parses tokens into measure objects (repeat/alternative markers retained in structure).
#### `measures_playing_order(measures: list[TokenMeasure], tokens: bool = False) -> list[int] | list[list[str]]`
Computes actual playback order considering repeats and alternatives. If `tokens=True`, returns the measures’ token lists in order rather than indices.
---
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Commit: `git commit -m "feat: add your feature"`
4. Push: `git push origin feature/your-feature`
5. Open a Pull Request
---
## License
Released under the **MIT License**. See [LICENSE](LICENSE).
Original project **dadaGP** by `dada-bots` is MIT as well.
Raw data
{
"_id": null,
"home_page": null,
"name": "acoustic-solo-dadaGP",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "music, guitar, tablature, tokenization, audio",
"author": null,
"author_email": "Austin Liu <austin_f_liu@brown.edu>, Claude Hu <zh4nh@virginia.edu>",
"download_url": "https://files.pythonhosted.org/packages/2e/d5/c0de362119e2b5771e75ce791888dd07f9d4dbdb7ae8e6379b723c8b37db/acoustic_solo_dadagp-0.1.0.tar.gz",
"platform": null,
"description": "# acoustic-solo-dadaGP\n\nA modification of [DadaGP](https://github.com/dada-bots/dadaGP) tailored for **acoustic solo guitar** workflows. It supports alternative string tunings and multi\u2011track acoustic/clean guitar parts, with a simple CLI and a small public Python API.\n\n---\n\n## Table of Contents\n\n1. [Background & Attribution](#background--attribution) \n2. [What\u2019s Changed](#whats-changed) \n3. [Features](#features) \n4. [Installation](#installation) \n5. [Quick Start](#quick-start) \n6. [CLI Reference](#cli-reference) \n7. [Python Reference](#python-reference) \n8. [Contributing](#contributing) \n9. [License](#license)\n\n---\n\n## Background & Attribution\n\nThis project is a **fork** of [`dada-bots/dadaGP`](https://github.com/dada-bots/dadaGP). Credit to the original authors for the foundational GP\u2194\ufe0etoken pipeline.\n\n---\n\n## What\u2019s Changed\n\n- **Enhanced Acoustic Support** \u2014 optimized defaults and checks for acoustic/clean guitar usage.\n- **Compatibility with pyguitarpro** \u2014 works with `pyguitarpro>=0.9`.\n- **Alternative Tunings** \u2014 supports non\u2011standard tunings (drop D, Celtic, etc.).\n- **Multi\u2011track Handling** \u2014 process up to 3 acoustic/clean tracks; optional merge\u2011down to one.\n- **Refined CLI** \u2014 ergonomic `asdadagp` tool for encode/decode/process/info.\n- **Token Utilities** \u2014 helpers for measure splitting, repeats/alternatives, and tuning extraction.\n\n---\n\n## Features\n\n- Convert `.gp3/.gp4/.gp5/.gpx` \u21c6 token text files\n- Optional **track merge**: keep only the first acoustic/clean track and strip `cleanX:` prefixes\n- **Measure & repeat analysis** helpers (playing order, measure objects)\n- Basic **file validation / info** summaries\n- Small **Python API** for scripting\n\n---\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install acoustic-solo-dadaGP\n```\n\n### From source\n\n```bash\ngit clone https://github.com/austinliu05/acoustic-solo-dadaGP.git\ncd acoustic-solo-dadaGP\npip install -e .\n```\n\nPython >=3.8 is required.\n\n---\n\n## Quick Start\n\n```bash\n# Encode a Guitar Pro file to tokens\nasdadagp encode song.gp5 tokens.txt --artist \"John Doe\"\n\n# Decode tokens back to Guitar Pro\nasdadagp decode tokens.txt song_out.gp5\n\n# Process tokens: merge to single acoustic track\nasdadagp process tokens.txt processed.txt --merge-tracks\n\n# Process tokens with structured measures JSON (includes tuning & playing order)\nasdadagp process tokens.txt processed.json --merge-tracks --measures\n\n# Inspect file info (works for both .gp* or token files)\nasdadagp info song.gp5\nasdadagp info tokens.txt\n```\n\n---\n\n## CLI Reference\n\nThe package installs the `asdadagp` command.\n\n### `encode` \u2014 Guitar Pro \u2192 tokens\n\n```\nasdadagp encode INPUT.gp[3|4|5|x] OUTPUT.txt [--artist NAME] [--tuning]\n```\n\n- `INPUT.gp*` \u2014 Guitar Pro file to encode\n- `OUTPUT.txt` \u2014 destination token file (one token per line)\n- `--artist NAME` \u2014 optional first\u2011line artist token (default: `\"Unknown\"`)\n- `--tuning` \u2014 if set, append tuning info to note tokens; otherwise only string tunings in the header\n\n### `decode` \u2014 tokens \u2192 Guitar Pro\n\n```\nasdadagp decode INPUT.txt OUTPUT.gp5\n```\n\n- `INPUT.txt` \u2014 token file produced by `encode`/processing\n- `OUTPUT.gp5` \u2014 Guitar Pro output (GP5 format is typical target)\n\n### `process` \u2014 transform token streams\n\n```\nasdadagp process INPUT.txt OUTPUT.(txt|json) [--merge-tracks] [--measures]\n```\n\n- `--merge-tracks` \u2014 Merge all tracks into 1 (otherwise it keeps only the first acoustic/clean guitar track) and\n remove `cleanX:` prefixes (e.g., `clean0:note:s6:f0:D3 \u2192 note:s6:f0:D3`)\n- `--measures` \u2014 output a **JSON** object with:\n - `tokens` \u2014 index\u2192token map (all processed tokens)\n - `measures` \u2014 list of per\u2011measure token lists\n - `playing_order` \u2014 measure indices in actual playback order accounting for repeats/alternatives\n - `tuning` \u2014 string tuning extracted from tokens\n\n> If `--measures` is used, `OUTPUT` **must** end with `.json`.\n\n### `info` \u2014 summarize a file\n\n```\nasdadagp info INPUT.(gp3|gp4|gp5|gpx|txt)\n```\n\n- For `.gp*` files: prints title/artist/album/track count/measure count/tempo + per\u2011track tunings\n- For token files: prints token counts and rough token\u2011type histogram\n\n---\n\n## Python Reference\n\nImport from the top\u2011level package `asdadagp`:\n\n```python\nfrom asdadagp import (\n __version__,\n # main conversions\n asdadagp_encode, guitarpro2tokens,\n asdadagp_decode, tokens2guitarpro,\n # processing helpers\n get_string_tunings, tracks_check, tokens_to_measures, measures_playing_order,\n # utilities\n get_tuning_type, get_fret, convert_spn_to_common,\n # constants\n instrument_groups, supported_times, wait_token_list2,\n)\n```\n\n### Conversions\n\n#### `asdadagp_encode(input_file: str, output_file: str, note_tuning: bool, artist_token: str) -> None`\nEncodes a Guitar Pro file into a token text file.\n- **input_file**: path to `.gp3/.gp4/.gp5/.gpx` file \n- **output_file**: path to write tokens (one per line) \n- **note_tuning**: if `True`, append tuning to note tokens \n- **artist_token**: first\u2011line artist token (e.g., `\"John Doe\"`) \n\nRelated lower\u2011level function:\n\n#### `guitarpro2tokens(song: guitarpro.Song, artist: str, verbose: bool, note_tuning: bool) -> list[str]`\nConverts an in\u2011memory `guitarpro.Song` into tokens.\n\n#### `asdadagp_decode(input_file: str, output_file: str) -> None`\nDecodes a token text file back into a Guitar Pro file. \nRelated lower\u2011level function:\n\n#### `tokens2guitarpro(all_tokens: list[str], verbose: bool = False) -> guitarpro.Song`\nBuilds an in\u2011memory `guitarpro.Song` from tokens.\n\n### Processing\n\n#### `get_string_tunings(tokens: list[str]) -> list[str]`\nExtracts per\u2011string tunings from a token list.\n\n#### `tracks_check(tokens: list[str], merge_track: bool) -> list[str]`\nOptionally merges to the first acoustic/clean track and removes `cleanX:` prefixes.\n\n#### `tokens_to_measures(tokens: list[str]) -> list[TokenMeasure]`\nParses tokens into measure objects (repeat/alternative markers retained in structure).\n\n#### `measures_playing_order(measures: list[TokenMeasure], tokens: bool = False) -> list[int] | list[list[str]]`\nComputes actual playback order considering repeats and alternatives. If `tokens=True`, returns the measures\u2019 token lists in order rather than indices.\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Commit: `git commit -m \"feat: add your feature\"`\n4. Push: `git push origin feature/your-feature`\n5. Open a Pull Request\n\n---\n\n## License\n\nReleased under the **MIT License**. See [LICENSE](LICENSE). \nOriginal project **dadaGP** by `dada-bots` is MIT as well.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2020 Dadabots\n Copyright (c) 2025 Austin Liu and Ziyang Hu\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Guitar tablature tokenization and processing toolkit.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/austinliu05/acoustic-solo-dadaGP",
"Source": "https://github.com/austinliu05/acoustic-solo-dadaGP"
},
"split_keywords": [
"music",
" guitar",
" tablature",
" tokenization",
" audio"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5583c0e12b4da8742630d6b28cdf341bfef8555ddba7a7904178a54dcdbb218c",
"md5": "24c913d42c51480dd88161d861d655da",
"sha256": "9d84b34bfa63257d0416816b7d17c27733b881e052ccf0ad7291a0aecd0efb6b"
},
"downloads": -1,
"filename": "acoustic_solo_dadagp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24c913d42c51480dd88161d861d655da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54063,
"upload_time": "2025-10-10T20:21:48",
"upload_time_iso_8601": "2025-10-10T20:21:48.311238Z",
"url": "https://files.pythonhosted.org/packages/55/83/c0e12b4da8742630d6b28cdf341bfef8555ddba7a7904178a54dcdbb218c/acoustic_solo_dadagp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2ed5c0de362119e2b5771e75ce791888dd07f9d4dbdb7ae8e6379b723c8b37db",
"md5": "abb2455a7c0b4981fa6ed2019b3749ec",
"sha256": "d3c19265ebb8427b1c8312b8bcb74b02a93a309e3f6d792a384d927ea0b577bb"
},
"downloads": -1,
"filename": "acoustic_solo_dadagp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "abb2455a7c0b4981fa6ed2019b3749ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 54931,
"upload_time": "2025-10-10T20:21:49",
"upload_time_iso_8601": "2025-10-10T20:21:49.823066Z",
"url": "https://files.pythonhosted.org/packages/2e/d5/c0de362119e2b5771e75ce791888dd07f9d4dbdb7ae8e6379b723c8b37db/acoustic_solo_dadagp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 20:21:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "austinliu05",
"github_project": "acoustic-solo-dadaGP",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "PyGuitarPro",
"specs": [
[
">=",
"0.9"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0.0"
]
]
}
],
"lcname": "acoustic-solo-dadagp"
}
