Setting Up PyHARP

HARP can run any Gradio app that follows a few conventions, and PyHARP is the Python library that applies them. This page explains how HARP talks to such an app, installs PyHARP, and runs one of its examples in HARP.

How It Works

HARP reaches an app through the Gradio API, at three endpoints that PyHARP creates:

• controls returns the model card (name, author, description, and tags) and a description of each component, which HARP draws as controls and tracks.
• process receives the input files and control values, runs the processing function of the app, and returns the output files and labels.
• cancel stops the job that the same copy of HARP started.

PyHARP provides the pieces of such an app:

• ModelCard, which describes the model.
• build_endpoint, which connects the Gradio components to a processing function, process_fn, and creates the three endpoints. It runs process_fn in a worker process, so that Cancel in HARP stops the work, and names each returned file after the model and the output.
• Helpers for audio (load_audio, save_audio), MIDI (load_midi, save_midi), and labels (LabelList, AudioLabel, MidiLabel).
• Tags that place a model in the taxonomy of HARP: Category, Subcategory, SampleRate, and Channels.

Each Gradio component becomes part of the model tab in HARP:

• gr.Audio(type="filepath") is an audio track, and gr.File(type="filepath", file_types=[".mid", ".midi"]) a MIDI track, as an input or an output.
• gr.File(type="filepath") with other file types is a file picker as an input, and a file as an output.
• gr.Slider, gr.Number, gr.Dropdown (a multiselect with multiselect=True), gr.Checkbox, and gr.Textbox are a slider, a number box, a dropdown, a toggle, and a text box, as inputs alone.
• gr.JSON, returning a LabelList, draws labels over an output track.

The README of PyHARP documents the library in full, and our deployment guidelines describe the conventions the models we host follow.

Install

PyHARP requires Python 3.10 or newer. Install it into an environment of its own, so that its dependencies, and those of each model you deploy, stay apart from the rest of your system:

python3 -m venv .venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
pip install "git+https://github.com/TEAMuP-dev/pyharp.git@v0.4.2"

This also installs Gradio, the audiotools of Descript (which brings PyTorch and librosa), and symusic for MIDI. Install FFmpeg as well, e.g., with brew install ffmpeg on macOS or sudo apt install ffmpeg on Ubuntu, since several audio libraries decode compressed formats through it.

Versions

HARP 4.0.0 pairs with pyharp 0.4.2, and the two are released together. The root VERSION file sets the application version through CMake.

PyHARP 0.4.2 installs a Gradio of at least 6.13, and below 7. HARP calls the /gradio_api/call/ endpoints that Gradio 5.0 introduced, so an app on Gradio 4.x or earlier cannot load. An app on Gradio 5.x loads, but cannot tell HARP why a job failed.

Run an Example

PyHARP ships with four examples, minimal templates for each combination of input and output media, and a tester of every component:

• pitch_shifter is audio in and audio out: one track in, one control, and one track out.
• midi_pitch_shifter is the same shape, on MIDI tracks.
• midi_synthesizer takes MIDI and returns audio, so its tracks differ in media type.
• ui_tester takes anything and returns audio, MIDI, and a file: every control, track, and label type, with no real processing.

To run the MIDI synthesizer, which renders a MIDI file to audio with a soundfont, clone PyHARP and install it in editable mode, which covers everything the examples import:

git clone https://github.com/TEAMuP-dev/pyharp
pip install -e pyharp
python pyharp/examples/midi_synthesizer/app.py

The first run downloads the MuseScore General soundfont. Once the app is ready, it prints its addresses:

* Running on local URL:  http://127.0.0.1:7860
* Running on public URL: https://<RANDOM_ID>.gradio.live

The local URL serves the app to your own machine, on the next free port if 7860 is taken. The public URL is a Gradio share link, which forwards to the app from anywhere until it expires after a week, or until the app stops. Open the local URL in a browser to try the app on its Gradio page.

Open It in HARP

1. On the Home tab of HARP, click Custom Path....
2. Enter the local URL, e.g., http://localhost:7860, and click Load. The model opens in a tab of its own, and keeps a card on the Home tab.
3. Drag a MIDI file onto the Input MIDI track, and select Process. The rendered audio appears in the Synthesized Audio track.

HARP reads the interface of an app when it loads the model, so after changing a component, close the tab of the model and open it again from its card. Stop the app with Ctrl+C.

Next Steps

• Example 1 walks through a small model that detects the key of a song.
• Example 2 walks through a larger one that separates stems on a GPU.
• Hosting Models puts an app online, so that it runs without your machine.