» Dezrann corpus/developer documentation

External Services for Dezrann

Dezrann does not provide any built-in analytical or generative pipeline. More generally, Dezrann is agnostic to any processing of music data. Users and developers are welcome to use their own analysis models and tools, in particular through external services.

Dezrann sends to such an external service any music data (“sources”). The service can do whatever processing it wants, and sends back to Dezrann updated or new music data.

The following sections show the underlying formats as well as ready-to-use Python templates to set up such a service. As of Q3 2026, the support of these external services is being progressively expanded. Please contact us for any details and/or to test/fix/deploy your service.

Specification

An external service is defined by the following data:

    "generate-chords": {
        "doc": "Generate chords",
        "api": "https://service.org/generate-chords",
        "needs": ["tab", "selection"] ,
        "parameters": { "lambda": "4.23" }
    }

The generate-chords service here needs a tablature (tab) and one or several region(s) (selection). Any source that Dezrann can display can be used (score, tab, midi, audio, video, analysis, selection, lyrics, images, see Sources). The parameter lambda, with here a default value, could be changed from within the Dezrann UI (todo).

Dezrann sends a POST request to https://service.org/generate-chords with the following payload, that is a .json describing a piece as specified here, with an additional query bloc:

{
    "opus": { },
    "sources": [
    {
      "id": "carcassitab",
      "tab": "https://gitlab.com/algomus.fr/dezrann/dezrann-front/-/raw/dev/public/local-corpus/carcassitab/tab/carcassitabpub-sansliaisons.gp"
    },
    {
      "id": "regions",
      "selection": "https://dezrann.net/tmp/tf54d5e.dez"
    },
    {
      "id": "an-ignored-source",
      "bla": "foo" 
    }
    ],
    "query": {
       "action": "generate-chords",
       "lambda": "4.23",
       "ref-source": [ "carcassitab", "regions" ]
    }   
}

The service should return the same .json, slightly modified, while creating or updating some sources, here the carcassitab tab:

{
    "opus": { },
    "sources": [
    {
      "id": "carcassitab",
      "tab": "https://service.org/tmp/df6z7kz.gp"
    },
    {
      "id": "regions",
      "selection": "https://dezrann.net/tmp/tf54d5e.dez"
    },
    {
      "id": "an-ignored-source",
      "bla": "foo" 
    }
    ],
    "query": {
       "action": "generate-chords",
       "lambda": "4.23",
       "ref-source": [ "carcassitab", "regions" ],
    },
    "result": {
       "log": "measures 5 and 6 generated",
       "ref-source-updated": [ "carcassitab" ]
    }
}

Python Templates

Setting up such a service can be done with the Dezrann Python bindings.

The examples/service.py shows a template for a simple Flask server that adheres to the above specification. The actual music processing takes place in the process function, which here works on an audio source and a selection.

def process(piece: Piece, sources: list, parameters) -> Piece:
    """A simple process on an selection and an audio."""
    assert len(sources) >= 2
    assert isinstance(sources[0], AudioSource)
    assert isinstance(sources[1], SelectionSource)

    audio = sources[0].data
    selection = sources[1].analysis
    shift = parameters.get('shift', 4.0)

    # Process
    # - Creates a label indicating the size of the audio
    # - Shift label(s) in the selection by 'shift'
    analysis = Analysis()
    analysis += Label(start=0, tag=f'Audio: {len(audio)} bytes')
    for label in selection:
        label.start += shift
        analysis += label

    # Save and return
    print("  ==>", analysis)
    analysis_file = f"{str(uuid4())[:8]}.dez"
    analysis.save(f"{TMP_DIR}/{analysis_file}")
    piece += AnalysisSource(f"{STATIC_URL}/{analysis_file}", id='result')

    piece.d['result'] = {
        'log': f'created analysis with {len(analysis)} labels',
        'timestamp': datetime.now().isoformat()
    }

    return piece