# MuScriptor Large — бандл и инструменты

Репозиторий-склад для [MuScriptor Large](https://huggingface.co/MuScriptor/muscriptor-large):
веса, упаковщик, проверка целостности и сборщик самодостаточного архива на Kaggle.

## Что здесь лежит

| Файл | Что делает |
|---|---|
| `bundle/tools/verify_model.py` | Читает заголовок safetensors, сверяет размеры с конфигом, считает параметры, по флагу `--hash` отдаёт sha256. Память не расходует: читает только заголовок. |
| `bundle/tools/pack_bundle.py` | Пакует веса, конфиг, карточку, инструменты и `manifest.json` в один `.tar` без сжатия. Хеш считается на лету. |
| `bundle/tools/kaggle_build_ai.py` | Сборщик для Kaggle: скачивает веса, проверяет, собирает архив (и/или fp16), заливает сюда же в `bundle/`. |
| `muscriptor_dynamics.py` | Громкость из аудио: у MuScriptor выхода velocity нет, модуль меряет RMS по записи и проставляет velocity в MIDI. |
| `transcript_fix.py` | Пост-обработка нот: уточнение онсетов по производной энергии, снятие фантомов, склейка дублей, осторожный добор. |
| `merge_transcriptions.py` | Голосование по нескольким проходам: выживает то, что подтвердили минимум `--votes` проходов. |
| `pianoify_colab.py` | Полная ячейка Colab: Pianoify + MuScriptor, job API, туннели, вотчдог. |
| `muscriptor_patch.py` | Патч той ячейки: режим `muscriptor`, разбор MIDI с velocity, пропуск загрузки модели в фортепианном режиме. |
| `bundle/README_BUNDLE.md` | Этот файл. |

## Что внутри бандла

`muscriptor-large-bundle.tar` (~5.1 ГБ, без сжатия) содержит:

```
manifest.json            версия, время сборки, параметры модели, sha256 весов, лицензии
model/model.safetensors  5.09 ГБ, 394 тензора, 1366 млн параметров, F32
model/config.json        dim 1536, heads 24, layers 48, card 1395
model/README.md          карточка исходной модели
tools/*.py               те же инструменты, что в репозитории
```

Сжатие не применяется осознанно: safetensors это плотные числа, gzip даёт около
2% выигрыша и десятки минут CPU. Размер архива предсказуем и равен сумме частей.

## Проверка

```bash
python tools/verify_model.py --model-dir muscriptor-large
```

Вывод на настоящих весах:

```
[30%] файл: 5.09 ГБ | данные: 5.09 ГБ | заголовок: 43.15 КБ
      тензоров: 394 | типы: {'F32': 394}
      параметров: 1366.4 млн
[50%] размеры сходятся байт в байт
      выходная голова: linears.0.weight -> 1395 токенов
[100%] итог: ГОДНО
```

## Сборка на Kaggle

1. В ноутбуке включи Internet (Settings > Internet on).
2. Add-ons > Secrets > добавь `HF_TOKEN` с правом записи, включи доступ для ноутбука.
3. Запусти:

```python
!wget -q -O tools.zip https://huggingface.co/Nokia123543/muscriptor-large-fork/resolve/main/tools.zip
!unzip -oq tools.zip -d tools
!python tools/kaggle_build_ai.py
```

Скрипт печатает проценты по этапам: скачивание, проверка заголовка, запись архива,
загрузка. В конце даёт ссылки на файлы в `bundle/`.

Режимы:

```bash
python tools/kaggle_build_ai.py --mode bundle   # только tar ~5.1 ГБ (по умолчанию)
python tools/kaggle_build_ai.py --mode fp16     # тяжёлые веса -> float16, ~2.6 ГБ
python tools/kaggle_build_ai.py --mode both     # и то, и то
python tools/kaggle_build_ai.py --source-dir /kaggle/input/... --no-upload
```

Память и диск: для `--mode bundle` нужно около 11 ГБ свободного места (5.09 ГБ
исходник + 5.1 ГБ архив). Для `--mode fp16` нужен GPU или хотя бы 11 ГБ RAM,
потому что `load_file` поднимает тензоры целиком; на Kaggle с 2×T4 это проходит.

## Лицензии

- Веса: **CC-BY-NC-4.0** — некоммерческое использование. В платном продукте их
  использовать нельзя, это записано и в `manifest.json`.
- Код инструментов и патчей: MIT.
- Названия и товарные знаки принадлежат их владельцам.

## Метрики и оговорки

- 1366.4 млн параметров, F32, 394 тензора, выходная голова на 1395 токенов.
- MuScriptor не предсказывает громкость: velocity берётся из `muscriptor_dynamics.py`
  измерением записи, либо из специализированной фортепианной модели.
- Для сольного фортепиано точнее специализированные модели; для группы и рока
  MuScriptor остаётся основным выбором.