Guía de MuScriptor | ai.manz.dev

1. Introducción

MuScriptor es un modelo open source de transcripción musical automática desarrollado por Kyutai y Mirelo. Le puedes dar audio musical y lo procesará y te devolverá las notas que toca cada instrumento en forma de fichero MIDI y, si quieres, de partitura.

Si en la guía de whisper.cpp convertíamos voz en texto, aquí damos el salto a la música: convertimos un audio en notas. Puedes probarlo sin instalar nada en muscriptor.kyutai.org, pero en esta guía te voy a explicar como ejecutarlo en local, en tu propio equipo, de modo que no dependas de la web o puedas usarlo de forma privada:

Canción

MuScriptor

MIDI

Partitura

¿Qué hace interesante a Muscriptor?

🎹 Multi-instrumento: Detecta guitarras, bajos, piano, batería, cuerdas, vientos, voces...
🎶 MIDI: Permite generar un fichero MIDI (editable en cualquier DAW).
🎼 PDF: Permite generar partituras o PDF (compatible con MusicXML y tablaturas).
🔒 100% local: Funciona sin conexión y sin enviar tu música a Internet.
⚖️ Tres modelos bastante pequeños (small, medium y large) para ajustarse a tu hardware.
🧰 Web, CLI y API de Python: ideal para usuario casual como para automatización.

📌 Como se trata de modelos pequeños, no hace falta grandes prestaciones de hardware para hacer funcionar Muscriptor. MuseScore 4+ sólo es necesario si quieres generar partituras.

2. Instalación

MuScriptor es una aplicación Python, así que lo más sencillo es utilizar uv, un gestor de paquetes extremadamente rápido que además nos permite ejecutar el programa con uvx sin instalarlo de forma permanente.

1) Instalar uv

En Linux, macOS o WSL, desde una terminal:

curl -LsSf https://astral.sh/uv/install.sh | sh

Si usas Windows, desde PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

En cualquier caso, puedes comprobar si se ha instalado correctamente:

uv --version

2) Usar MuScriptor

Con uvx podemos lanzar MuScriptor sin necesidad de instalarlo manualmente. La primera vez descargará el paquete y sus dependencias necesarias (incluido PyTorch, que pesa bastante), así que tomate con calma el primer arranque:

uvx muscriptor serve

En Windows, el backend por defecto de PyTorch es CPU. Para usar la GPU hace falta indicarlo explícitamente con uvx --torch-backend=cu128 muscriptor serve.

Una vez instalado todo lo necesario, te mostrará un mensaje de error, ya que aún no has descargado el modelo de IA necesario.

3. Descarga de modelos

Los pesos de MuScriptor están en HuggingFace, pero están restringidos a cuentas gratuita que acepten la licencia CC BY-NC 4.0 en HuggingFace. El acceso se concede automática y gratuitamente, pero es un paso obligatorio.

Existen tres tamaños del modelo, sólo tienes que elegir uno y descargarlo:

Modelo	Parámetros	Tamaño	VRAM aprox.	Recomendación
`small`	`103M`	`0.41GB`	~2GB	CPU o GPUs modestas
`medium`	`307M`	`1.23GB`	~4GB	El mejor equilibrio
`large`	`1.4B`	`5.47GB`	~8GB+	Máxima calidad, con GPU

Si utilizas el modelo large, sólo necesitarás el fichero model.safetensors, en caso contrario, descarga también el config.json y dejalo junto al modelo. Asumamos que vamos a utilizar el modelo muscriptor-large, que es el que mejor calidad tiene:

mkdir -p ~/.models
mv model.safetensors ~/.models/muscriptor-large.safetensors

Ahora sólo es necesario indicar el modelo a la hora de abrir MuScriptor.

4. Transcribir música

La forma más cómoda de empezar es la interfaz web, que es la misma que la demo oficial pero ejecutándose en tu equipo. Con el modelo ya descargado:

uvx muscriptor serve --model ~/.models/muscriptor-large.safetensors

Si te falta VRAM, puedes probar a bajar la precisión de los modelos y añadir el flag --dtype float16. Por defecto muscriptor serve utiliza --dtype float32.

Entonces verás algo similar a esto:

Loading model…
INFO:     Started server process [8412]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8222 (Press CTRL+C to quit)

Abre http://127.0.0.1:8222 en el navegador para comenzar a usar MuScriptor. Aquí tienes un ejemplo de video con una transcripción completa donde voy mostrando la diferencia entre la canción original y la versión transcrita, que como se puede ver, es bastante fiel:

Si te gusta la canción, ve a Manz.dev y pulsa en la esquina superior-derecha.

Sólo tienes que elegir la canción para comenzar a transcribirla. Acepta MP3, WAV, FLAC, OGG, M4A, AIFF y Opus.

5. Características de MuScriptor

Entre las funcionalidades que permite, puedes hacer las siguientes:

🎷 Puedes indicar los instrumentos que quieres (evita añadir otros)
🎹 Transcribe va identificando las notas y mostrándolas poco a poco
🔇 Puedes mutear o escuchar sólo un instrumento
🎼 Con Tempo & bars puedes corregir el ritmo y velocidad

Con uvx muscriptor list-instruments puedes ver la lista de instrumentos posibles.

Descargar

El botón Download tiene un menú con cuatro opciones:

Opción	Qué obtienes
MIDI file	El `.mid` de la transcripción, con opciones de cuantización
WAV - transcription only	Sólo las notas transcritas, tocadas con un SoundFont (mono)
WAV - stereo with original	El audio original a la izquierda y la transcripción a la derecha
Sheet music	PDFs por instrumento, tablaturas, MusicXML y el MIDI cuantizado

Recuerda que la opción Sheet music necesita MuseScore 4 y las dos de WAV necesitan FluidSynth (ver más abajo). Si no usas ninguna de estas, no hace falta instalarlos.

6. Automatizar transcripción

Para automatizar o procesar muchos ficheros, hacerlo desde una CLI es lo más cómodo:

uvx muscriptor transcribe cancion.mp3 \
  --model ~/.models/muscriptor-large.safetensors

Mientras trabaja, te irá contando lo que hace, y finalmente guardará el MIDI:

Loading model…
[muscriptor] load audio: 0.08s
[muscriptor] audio: 184.3s → 37 chunk(s) of 5.0s
[muscriptor] build conditions: 0.94s
[muscriptor] generate total: 63.41s
[muscriptor] transcribe total: 64.80s (184.3s audio)
Saved MIDI to cancion.mid

Con uvx muscriptor transcribe --help puedes ver las opciones de transcripción disponibles.

7. Partituras y descargas

Generar partituras requiere tener instalado MuseScore 4 o superior. En Linux o WSL los repositorios pueden descargarse en AppImage, por lo que sólo hay renombrarlo y moverlo a tu raíz con este nombre:

mv MuseScore-Studio-4.7.6-x86_64.AppImage ~/MuseScore.AppImage

Con esto ya debería funcionar. Si además quieres exportar en .WAV alguna transcripción de audio de la canción, necesitarás tener instalado FluidSynth:

sudo apt install fluidsynth

El SoundFont (MuseScore_General.sf2) se descarga solo la primera vez y se cachea en ~/.cache/muscriptor/. El formato sheets es el que genera la partitura y se lanza así:

uvx muscriptor transcribe cancion.mp3 \
  --model ~/.models/muscriptor-large.safetensors \
  --format sheets \
  --output partitura/

El directorio de salida debe no existir o estar vacío; si no, el comando falla para no mezclar PDFs con otros ficheros. La carpeta quedaría así:

partitura/
├── score.mid                   // La transcripción, como MIDI cuantizado
├── score.musicxml              // La partitura, como MusicXML
├── full_score.pdf              // Todos los instrumentos en un sistema
├── 01_electric_guitar.pdf      // Un PDF por instrumento
├── 01_electric_guitar_tab.pdf  // Tablatura para los de cuerda
├── 02_electric_bass.pdf        // ...
├── 02_electric_bass_tab.pdf
└── 03_drum_kit.pdf