Skip to content
Skills Library
Education · Conversion & formats

makebraille

/makebraille

Use when converting MusicXML or CapX scores to music Braille via dzb lesen's MakeBraille service. Vault-backed login, batch conversion, verified end-to-end plumbing.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
3
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/makebraille.py, scripts/run.sh, scripts/vault_add_makebraille.py

What it does and when to use it

Use when converting MusicXML or CapX scores to music Braille via dzb lesen's MakeBraille service. Vault-backed login, batch conversion, verified end-to-end plumbing.

Original author description

Use when converting MusicXML or CapX scores to music Braille via dzb lesen's MakeBraille service. Vault-backed login, batch conversion, verified end-to-end plumbing.

How it works

  1. Vorgehen
  2. Zugangsdaten
  3. Benutzung
  4. Ergebnis: kommt per E-Mail
  5. Profile und Antwortformen (Stand 31.10.2026)
  6. Stand und Grenzen
  7. Stolpersteine
Original SKILL.md headings · 148 lines, 1,347 words
SKILL.md preview
---
name: makebraille
description: "Use when converting MusicXML or CapX scores to music Braille via dzb lesen's MakeBraille service. Vault-backed login, batch conversion, verified end-to-end plumbing."
version: 0.1.0
author: Hermes Agent + Julian
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [braille, music, accessibility, musicxml, capx, dzb-lesen, vault, daisy]
    related_skills: [musicxml-engraving-accessibility, vector-score-to-musicxml]
---

# MakeBraille (dzb lesen) — MusicXML nach Musikbraille

Konvertiert MusicXML (und CapX) über den Online-Dienst von dzb lesen in Musikbraille:
**https://makebraille.dzblesen.de/MakeBraille** — Login nötig, Benutzername und Passwort
jeweils **max. 30 Zeichen**. Nutzungsbedingungen: nur privat/nicht-kommerziell,
gemeinfreie Werke sowie rechtmäßig genutzte urheberrechtlich geschützte Werke und eigene
Sätze; dzb lesen wertet die Nutzung aus und freut sich über Rückmeldung
(makebraille-support@dzblesen.de). Details siehe `references/makebraille-service.md`.

## Vorgehen

Für wiederkehrende Konvertierungen einen **Client + Skill** bauen und pflegen, nicht den Browser
bedienen: der Login wandert einmal in den Vault, danach läuft alles headless (auch aus Cron- und
Webhook-Sitzungen). Der Client gehört an den Vault, nicht an ein abgetipptes Passwort — jede
weitere Konvertierung soll ohne Zutun und ohne Interaktion auskommen. Reicht das Webformular
nicht, ist der Client die Stelle zum Nachziehen (`scripts/makebraille.py`), nicht ein zweiter
Ad-hoc-Aufruf.

## Zugangsdaten

Der Login liegt im Hermes-Credential-Vault, gebunden an die Origin
`https://makebraille.dzblesen.de` (Schema + Host, der Pfad zählt nicht). Anlegen — in einer
interaktiven Sitzung fragt `hermes vault add` das Passwort verdeckt ab:

```bash
printf 'login\ndzb lesen MakeBraille\nhttps://makebraille.dzblesen.de\nusername\n<BENUTZER>\n' | hermes vault add
```

Aus einer Datei (Zeile 1 Benutzer, Zeile 2 Passwort, oder `Benutzer:`/`Passwort:`) — legt den
Eintrag an und löscht die Datei danach:

```bash
scripts/vault_add_makebraille.py /pfad/zugang.txt
```

**Nie** ein Passwort im Chat annehmen: Gateway-Sitzungen (Matrix, Telegram, …) haben keinen
verdeckten Eingabekanal — alles Getippte landet im Modellkontext, in der Session-DB und auf dem
Plattformserver. Nur interaktive Oberflächen (CLI/TUI, Desktop-App) können Passwörter maskiert
einfangen. Hintergrund: Skill `hermes-agent`, `references/security-privacy.md`.

## Benutzung

`scripts/run.sh` startet den Client in der Hermes-Python-Laufzeit, damit er den Vault lesen kann
(das Passwort wird im Prozess aufgelöst und nie ausgegeben; `HERMES_PY=/pfad/python3` erzwingt
eine andere Laufzeit):

```bash
scripts/run.sh check                       # Login testen, Formulare der Startseite listen
scripts/run.sh dump --url /MakeBraille     # Seite nach dem Login als HTML sichern
scripts/run.sh convert werk.musicxml --out out
scripts/run.sh batch 'musicxml/*.musicxml' --out out
scripts/run.sh config                      # aktives Profil, Empfängeradresse, Einstellungen
scripts/run.sh config --save --name NEU --email ADRESSE   # Profil klonen/ändern
```

`config` liest die Konfigurationsseite. Mit `--save` wird sie mit den **vorhandenen** Werten
abgeschickt und dabei nur Profilname (`--name`) und/oder Empfängeradresse (`--email`) ersetzt —
so entsteht aus einem bestehenden Profil ein Klon mit denselben Einstellungen. Achtung: die
Seite gehört zum echten Konto, unabgeschickt (`--name`/`--email` ohne `--save`) liest sie nur.

## Ergebnis: kommt per E-Mail

MakeBraille hat **keinen Download in der Weboberfläche**: die fertige Datei wird automatisch an
die Adresse geschickt, die im aktiven Profil steht (Absender `no-reply@dzblesen.de`, laut Hilfe
innerhalb von 30 Minuten, bei Ausbleiben Spam-Ordner prüfen). Für einen unbeaufsichtigten
Ablauf muss die Zieladresse also eine sein, die der Agent lesen kann (AgentMail-Postfach) — dann
ist der Kreislauf Upload → Mail → Datei einlesen geschlossen. Ein Profil auf eine
AgentMail-Adresse umzustellen ändert nur dieses Profil, nicht die eigenen.

## Profile und Antwortformen (Stand 31.10.2026)

* **Offen (31.10.2026): Zustellung an AgentMail.** Die Danke-Seite der Testkonvertierung mit dem
  Klon nannte `mimo@agentmail.to`, im AgentMail-Postfach kam die Mail aber auch nach 25 Minuten
  nicht an (43 Nachrichten im Postfach, alle von GitHub; keine Empfangs-Sperrliste aktiv,
  `GET /v0/inboxes/<id>/lists/receive/allow` ist leer). Zu klären: kann der Dienst an fremde
  Domains ausliefern (Adresse im Profil bestätigungspflichtig?), und nimmt AgentMail Post von
  `no-reply@dzblesen.de` an? Testmail vom Nutzer-Gmail an das Postfach klärt die zweite Frage;
  sonst makebraille-support@dzblesen.de fragen. Bis das geklärt ist, bleibt Julians `Chor`
  (Zustellung an sein Gmail, nachweislich zuverlässig) der sichere Weg.
* **Zustellung an Julians Gmail funktioniert (bestätigt 01.11.2026):** mit dem unveränderten Profil `Chor` hochgeladen, Ergebnis-Mails an `dreykorn.julian@gmail.com` kamen an (je Datei eine). Für Julians eigene Auslieferung also `Chor` verwenden, nicht umstellen.
* **Klon steht bereit:** Profil `Hermes-AgentMail` im Konto (Kopie von `Chor`, Empfänger
  `mimo@agentmail.to`, Stand 31.10.2026 feldweise geprüft: nur Adresse und Profilname weichen von
  `Chor` ab). Für eigene Läufe `--profile Hermes-AgentMail` setzen; `Chor` bleibt Julians Profil.
* **Klon anlegen ist eine Falle:** Werte nie als flaches `{name: value}`-Dict über alle Felder in
  Dokumentreihenfolge einsammeln — bei Radiogruppen gewinnt sonst der **letzte** Eintrag (jeder
  Radiotag trägt sein eigenes `value`), und der neue Profil wird zu einem Default-Profil (im
  Praxisfall: `country=usa`, `division=bobc`, `text_format=de_contracted`, `merge_parts=hybrid`,
  `user_profile=conductors_edition`, `makebraille_out_format=pef`). Richtig ist `_form_fields()`:
  nur angehakte Wahlfelder, ein Wert je Name. Danach gegen das Quellprofil zurücklesen und die
  Differenz prüfen (erwartet: nur `email` und Profilname). Und: die **Adresse erst in einem
  zweiten Speichervorgang** setzen — beim Anlegen wurde sie ignoriert.
* **Die Empfängeradresse ist profilweit.** Nachweis: Adresse im Klon geändert, `Chor` blieb
  unverändert. Beim **Anlegen** eines Klons mit `config --save --name NEU --email ADDR` wurde die
  neue Adresse nicht übernommen — erst ein zweiter Speichervorgang unter dem neuen Namen setzte
  sie. Also: anlegen, zurücklesen, Adresse ggf. nachziehen.
* **Profilwechsel ist ein eigener Schritt** (`mode=switch_uprofile`) und muss vor dem Upload
  passieren; danach prüfen (das aktiv gewählte `<option ... selected>`); ein
  `uprofile_selector` im Upload-POST allein wechselt das Profil nicht.
* **Leere Antwort (HTTP 200, 0 Byte) ist die häufigste Form — nicht hektisch wiederholen** (gemessen 01.11.2026, Profil `Chor`: von fünf Uploads kamen vier leer zurück, nur einer als Startseite mit „still being converted"). Der leere Body heißt nicht, dass die Datei nicht angenommen wurde — der POST kann verarbeitet und die Antwort verloren gegangen sein: der POST war gesendet, und die Konvertierung lief (Julian meldete am 01.11.2026 für zwei hochgeladene Dateien **zwei** Ergebnis-Mails, obwohl ein Versuch leer geantwortet hatte; die Zuordnung — je Datei eine oder dieselbe zweimal — war noch offen). Und **jeder** abgesetzte POST kann eine eigene Mail erzeugen: zwei Uploads derselben Datei brachten Julian am 01.11.2026 zweimal dieselbe Mail. Also **nicht** automatisch wiederholen — hochladen, dem Nutzer sagen, dass die Mail kommt, und erst auf seine Rückmeldung hin erneut senden — die Weboberfläche bietet keine Job-Liste, der Posteingang ist die einzige Prüfung.
* **Drei Antwortformen auf einen Upload:** (a) Danke-Seite „Your converted music Braille file
  will be sent to: <adresse>." — akzeptiert, nennt die Zieladresse (beste Bestätigung),
  (b) Startseite mit „Your file is still being converted, please wait." — angenommen,
  (c) leere Antwort (HTTP 200, 0 Byte) — häufigster Fall, aber NICHT automatisch wiederholen: jeder POST kann eine eigene Ergebnis-Mail erzeugen (Julian bekam dieselbe Mail zweimal). Nutzer informieren, nur auf seine Rückmeldung erneut senden. Welche Form
  kommt, hängt offenbar vom Serverzustand ab, **nicht** vom Profil: `Chor` und
  `Chor_Direktausgabe` haben feldweise identische Einstellungen (44/46 gleich, nur der Name
  differiert) und lieferten dennoch beide Formen.
* **Der Upload-POST trägt die kompletten Profileinstellungen** (u. a. `email`, `paper_width`,
  `text_format`, `filter_*`) — nach dem Profilwechsel also immer das Formular der frischen Seite
  verwenden, nie ein vorher eingesammeltes.

Ohne Vault (andere Umgebung): `--user <name> --password-file <datei>`. Passwörter **nie** als
Kommandozeilenargument übergeben — sie stehen sonst in der Prozessliste.

## Stand und Grenzen

* **Geprüft:** Vault-Anlage über beide Wege, Vault-Auflösung, HTTP-Sitzung (Cookies), Login-POST
  auf `/MakeBraille` mit `login`/`passwd`/`mode=server_login` und die Fehlererkennung — eine
  falsche Kennung liefert wieder die Login-Seite, der Client meldet „Login abgelehnt".
* **Upload (am Nutzer bestätigt, 31.10.2026):** der POST geht mit den aus der Startseite gelesenen
  Formularfeldern und dem Dateifeld `file` (nimmt `.capx`, `.musicxml`, `.mxl`, `.mxml`, `.xml`,
  `.zip`; Profil/Schalter vorher per `switch_uprofile`) an `/MakeBraille`; zwei Testkonvertierungen
  kamen als Mail an. Der Dienst antwortet auch bei Annahme nur mit der Startseite — daraus lässt
  sich **keine** Bestätigung ableiten. Beleg ist allein die Ergebnis-Mail; eine Konvertierung gilt
  erst als erledigt, wenn die Datei da ist.
* **Profil/Einstellungen** (Stand 30.10.2026, Konto julian.dreykorn): Profile `Chor`,
  `Chor_Direktausgabe`, `Nach_Systemen_Fingersätze`, `Orgel`, `Orgel_Englisch`, `Profil1_20220206`;
  Felder `makebraille_out_format` (z. B. `braille`), `country`, `user_profile`, `text_format`,
  `division`, `merge_parts`. Formular-`mode`-Werte: `server_login`, `create`,
  `switch_uprofile`, `delete_uprofile`, `configuration`, `part_excerpt_edit`.
* **Kein Login = keine Auskunft:** Der Dienst beantwortet jeden Aufruf ohne gültige Sitzung mit
  HTTP 200 und der Login-Seite — deshalb prüft der Client den Inhalt, nicht den Statuscode.

## Stolpersteine

* Origin-Bindung ist exakt: ein für `dzblesen.de` gespeicherter Login gilt nicht für
  `makebraille.dzblesen.de` und umgekehrt.
* `https://dzblesen.de/makebraille` und `https://www.dzblesen.de/makebraille` leiten per 301 auf
  `https://makebraille.dzblesen.de/MakeBraille` weiter — immer die Endadresse als Origin nehmen.
* Der Vault-Eintrag gehört ins Standardprofil; in Cron-/Webhook-Sitzungen funktioniert er
  weiterhin (lokale Vault-Einträge brauchen keinen Prompt), in fremden Profilen nicht.
* Wahlfelder (`radio`/`checkbox`) müssen **nur angehakt** mitgeschickt werden, sonst setzt ein
  `--save` auf der Konfigurationsseite ungewollt die zuletzt gelesenen Werte. `FormParser` merkt
  sich `checked`/`disabled`, `_form_fields` verwirft nicht angehakte Wahlfelder.
* Neue Unterbefehle im Client brauchen `parents=[common]`, sonst lehnt argparse die globalen
  Optionen (`--out`, `--handle`, `--user`, `--password-file`) ab, sobald sie hinter dem
  Unterbefehl stehen (Optionen vor *und* nach dem Unterbefehl müssen funktionieren).
Files in this package (5)
  • SKILL.md 11 KB
  • references/makebraille-service.md 2 KB
  • scripts/makebraille.py 25 KB
  • scripts/run.sh 1 KB
  • scripts/vault_add_makebraille.py 3 KB

Versions

The database has no other skills named makebraille.

Database snapshot: 13.11.2026 · package version 2989e382896c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86vector-score-to-musicxml
    Use when transcribing vector PDF scores to MusicXML.
  • 100sheet-music-pdf-convert
    Turn a sheet music PDF (exported from notation software, scanned, or photographed) into editable MusicXML that opens in MuseScore, Dorico, Sibelius or Finale. Use when the user wants to edit, transpose, re-engrave or play back a score they only have as a PDF, asks to "convert…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.