[harrrp] Core

Item	Description
What is this?	Critical part of project harrrp, several python interfaces and tools for .yaml harmonica tabs.
What does it contain? Not a complete list, please see further sections.	Python interfaces to all historical harrrp harmonica tab schema versions, starting from minimum version 4.1.0. Tab difficulty estimator. index.csv creator.
What does it NOT contain?	Batch tab editor. Tab creator.
Why does it NOT contain some items?	Because the items in question are abstract programmatic text-editing tools, which are not unique nor native to project harrrp — they belong to a different project.

Installation

1. Clone the repository.
2. Install requirements pip install -r requirements.txt.

Usage

Since the tools in this repository are targeted towards batch non-editing operations on already existing harmonica tabs, the first step requires the user to actually provide the paths to these already existing harmonica tabs.

Define paths

Paths to existing harmonica tabs are defined using the tab_folders.txt file, located at the root of the project. The example contents could be as follows:

some/custom/path/tabs
c:\another\custom\path\tabs

d:\third\different\location\tabs

Run some tool

After defining paths to at least one existing folder with harmonica tabs, tool launchers become usable.

Please choose the autorun_*.py file according to current goals, open it with IDE of choice and run it.

Structure

Overall

The project contains several parts that nicely fit together and allow to easily accomodate future changes while preserving past versions and functionality.

Individual Parts

Name	Description	How to Locate
Some tool	Rather abstract data analysis tool that can be applied to any compatible user input, regardless of its origin or meaning. There can be many of them, they exist for different purposes.	Any file named src/some_*_Columns.
Some tool launcher	Wapper code that allows the user to one-click apply the tool of choice to any harrrp harmonica tabs without headaches or low-level considerations. There can be many of them, they exist for usage convenience.	Any file named autorun_*.py.
Some interface to specific harmonica tab schema version	Actual low-level programmatic interface to some specific harrrp harmonica tab. There are many of them, they evolve according to user needs.	Any file named src/format_*/Columns_Tab.py.
The interface chooser	One convenient endpoint that automatically chooses the correct programmatic interface for any given harmonica tab, freeing the developer from any worries regarding "how to process this specific tab". There is only one.	The file named src/some_TabFormat_Columns.py.

How They Communicate

	Some tool	Some interface to specific harmonica tab schema version	The interface chooser	Some tool launcher
Welcomes structural changes?	❌ Any functionality-adding changes are appended to the latest version. Any functionality-altering changes are not welcome and should be avoided as much as possible, because they may dramatically affect apps that rely on the output of this tool.	✔️ Any functionality-adding changes are appended to the latest version. Any functionality-altering changes are placed in the new version.	❌ Any functionality-adding changes are appended to the latest version. Any functionality-altering changes are not welcome and should be avoided as much as possible, because they may dramatically affect apps that rely on this code.	✔️ Must be as convenient as possible, usually calls appropriate methods from interface chooser, but in more complex cases can combine some tool with interface chooser.
Has to be compatible with...	No one.	👈 Some tool. Efficiently use tool's methods. 👉 The interface chooser. Provide some reserved endpoints to it.	No one.	👈 Some tool. Efficiently use tool's methods. 👈 The interface chooser. Efficiently use its methods.

Available Functionality

In this section the functionality of all available "some tools" and "some tool launchers" is listed.

Tool	Description	How to Locate
Estimate tab difficulty.	Analyze given input (that usually represents notes within some harmonica tab) and determine its actual real-life performance difficulty using sensible multifactor scoring system. Calculate the most optimal default sorting order (easiest → hardest) based on the assumption that the player is capable of consistently producing single notes.	The file named src/some_Difficulty_Columns.py. The file named autorun_IndexCsv.py.
Create convenient tab comparison table.	Provide quick overview of all harmonica tabs in specific user-defined root folder. Allow applications to access critical metadata regarding harmonica tabs without actually parsing them. Automatically calculate and save tab difficulty scores for future use.	The file named src/some_IndexCsv_Columns.py. The file named autorun_IndexCsv.py.
Process .midi attachments.	Embed externally-created timecodes into the actual harmonica tab so that the apps know which part of .midi to playback for any given line. Temporarily convert .midi data to simplified debug .csv with absolute timecodes so that app development becomes easier. Force all .midi files to comply with the MIDI Type 1 standard so that any application can reliably calculate correct timecodes.	The file named src/some_MidiText_Columns.py. The file named autorun_MidiCsv.py. The file named autorun_MidiType1Force.py. The file named autorun_PasteTimecodes.py.

Available Interfaces to Specific Schema Versions

versions:
  4.1.0: ok

License

The actual licenses are available per-flie, please see the source code.
Any files which contain data, unique to project harrrp, are subject to GPL v3.
Any general files which contain data, not unique to project harrrp, are subject to BSD0.
Any unmarked file is implied to be subject to either BSD0 or GPL v3, according to the statements above.