pianotrans: a desktop GUI wrapper for ByteDance piano transcription
Simple GUI for ByteDance's Piano Transcription with Pedals
At a glance
- What is it?
- pianotrans packages ByteDance's piano transcription model as a Windows build and a Nix package, so you can turn audio or video files into MIDI with pedals without touching Python. It is a packaging project, not a transcription model.
- Who is it for?
- Adopt pianotrans if you want ByteDance's transcription model behind a file picker on Windows 10, Debian Linux 10 or macOS 12.1 M1, and you are comfortable with a 1.5GB Windows archive or a Nix flake. Do not adopt it if you expect the author to tune transcription accuracy: the README states that as long as it gives you MIDI files, all other issues are out of scope, and points you to the upstream bytedance/piano_transcription issue tracker.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Nix, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What pianotrans actually adds to ByteDance's transcription model
The transcription itself comes from ByteDance's Piano Transcription, a PyTorch implementation of the paper "High-resolution Piano Transcription with Pedals by Regressing Onsets and Offsets Times." That model turns piano recordings into MIDI files that include pedal events. Running it normally means setting up Python, PyTorch and the piano_transcription_inference package, then calling the inference code yourself.
pianotrans is the layer around that. The README describes it as "a simple GUI and packaging for Windows and Nix on Linux/macOS." The repository holds PianoTrans.py, a flake.nix, a windows directory and a setup.py whose only declared dependency is piano_transcription_inference. So the target user is someone who has piano audio or video and wants a MIDI file, and does not want to maintain a Python environment to get one. The project's own FAQ sets the boundary explicitly: as long as it gives you MIDI files, everything else belongs upstream.
How the packaging works: one Python entry point, two delivery paths
There is a single Python module. setup.py declares py_modules=["PianoTrans"] and a console script entry point, pianotrans = PianoTrans:main. That one main function is what both the GUI and the command line start from, which is why the same binary can open a window or process a list of files.
The two delivery paths differ in what they bundle. The Windows release is a 1.5GB 7z archive containing PianoTrans.exe, a PianoTrans-CPU.bat fallback and RightClickMenuRegister.bat for a shell context menu. The Nix path builds the package from the flake; the changelog for 1.0.1 notes that the mido, soundfile, torchlibrosa and piano-transcription-inference overlays were removed because all patches were accepted in nixpkgs, which the entry says means more dependencies come from the Nix binary cache instead of being built locally.
File selection is manual in both cases: you choose files, hold CTRL (or Command on macOS) to select several, and results land in the same directory as the inputs. There is no watch folder and no batch manifest.
Installing pianotrans on Windows and running a first transcription
The Windows route needs no Python. Install the Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019 first, then unpack the archive with 7zip. The README warns that the download is 1.5GB and that you should close other apps to free memory, because inference needs at least 2GB free. Then run the executable from inside the unpacked directory:
PianoTrans.exeA GUI opens. Choose your audio or video files, hold CTRL to select more than one, and the MIDI results appear beside the source files. If GPU inference fails, the README points to the CPU fallback:
PianoTrans-CPU.batFor a right-click "Piano Transcribe" entry in Explorer, run RightClickMenuRegister.bat once. The changelog notes that if you upgrade from an earlier version, you need to re-run that script for the multi-file context menu to take effect.
Installing pianotrans with Nix on Linux or macOS
The README is explicit that the Nix guide assumes you already use Nix, and that non-Nix users should follow the upstream pip instructions instead. If you are on Nix, the first block installs Nix itself and enables flakes, which the flake-based install command requires:
sh <(curl -L https://nixos.org/nix/install) --daemon
mkdir -p ~/.config/nix
echo 'experimental-features = nix-command flakes' > ~/.config/nix/nix.confAfter that, pianotrans installs straight from the repository:
nix profile install github:azuwis/pianotransRunning pianotrans with no arguments opens the GUI. The CLI form takes files directly, which is the part worth knowing if you want to script it:
pianotrans file1 file2The changelog for 1.0.1 adds a --cli option to force the GUI off, useful when a display is not available. Upgrades go through the profile command, and the README shows the sequence with nix profile list first so you can find the profile index, then nix --option tarball-ttl 1 profile upgrade 0. The tarball-ttl override is there because the flake reference is otherwise cached.
Where pianotrans stops and the upstream project begins
The most important limitation is stated by the author rather than discovered by users. Asked whether transcription results can be improved, the README answers that the project is about packaging for bytedance/piano_transcription and that all other issues are out of scope, directing reports to the upstream issue tracker. If your complaint is wrong notes, missed pedals or a bad result on a particular recording, pianotrans is the wrong place to file it and the wrong project to fork for a fix.
The second constraint is memory. The stated requirement is at least 4GB, and the Windows instructions ask for at least 2GB free at run time, so a machine that is already busy will fail or swap badly. The third is platform coverage: the README lists Windows 7 or later (64-bit), Linux and macOS (Intel and M1) as requirements, but says only Windows 10, Debian Linux 10 and macOS 12.1 M1 are tested. Everything else is untested rather than supported. Finally, the Windows archive is a 1.5GB download, which is a real cost on a slow connection and a real cost in disk space for a tool you may run a handful of times.
Alternatives: Transkun, GiantMIDI-Piano and the upstream Python package
The closest comparison is the upstream piano_transcription_inference package that pianotrans itself depends on. Installing it with pip gives you the same model and the same MIDI output, but you own the Python environment, the PyTorch install and the invocation code. That is the right choice if you want to call transcription from your own script or run it on a server without a desktop. pianotrans is the right choice when you want a file picker and a packaged binary.
Transkun and GiantMIDI-Piano appear in the searches people run around this project, and they are separate transcription systems rather than wrappers. The difference in approach matters: pianotrans deliberately adds no model of its own, so its output quality is exactly the quality of ByteDance's model and its release cadence is tied to packaging concerns like PyTorch versions and Nix overlays. A project that ships its own model can tune accuracy; pianotrans cannot, and the author says so. If you need a hosted option, the searches also include online services, but pianotrans is a local desktop tool and the README describes no server component.
Maintenance, licensing and what an upgrade costs
The last push to the repository was on 2026-09-14, and the repository is not archived. The most recent tagged release is v1.0 from 2022-02-22, while setup.py declares version 1.0.1 and the changelog carries a 1.0.1 entry dated 2023-02-09, so the version string in the package and the newest release tag do not match. That is a packaging detail worth knowing before you pin anything by tag.
Upgrading on Nix is a profile operation, and the README's example shows a jump from a python3.9-pianotrans-0.2.1 store path to 1.0, which means an upgrade can move the Python and PyTorch versions underneath you. The 1.0.1 changelog is a good illustration of the cost: removing the mido, soundfile, torchlibrosa and piano-transcription-inference overlays changed where dependencies come from, which is a build-time change, not a behaviour change. On Windows, upgrades mean re-downloading the archive and re-running RightClickMenuRegister.bat. The repository does not state a licence, and the README does not discuss one, so anyone redistributing the Windows build or the Nix package should confirm the licensing terms of both this project and the upstream model before doing so.
Editorial conclusion
Adopt pianotrans if you want ByteDance's transcription model behind a file picker on Windows 10, Debian Linux 10 or macOS 12.1 M1, and you are comfortable with a 1.5GB Windows archive or a Nix flake. Do not adopt it if you expect the author to tune transcription accuracy: the README states that as long as it gives you MIDI files, all other issues are out of scope, and points you to the upstream bytedance/piano_transcription issue tracker. Verify first that you have at least 4GB of memory and, on Windows, that the Visual C++ Redistributable is installed before unpacking the archive.
Frequently asked questions
What is a piano transcription?
It is the process of converting a piano recording into a symbolic representation, in this case a MIDI file. pianotrans uses ByteDance's Piano Transcription model, which the README describes as transcribing piano recordings into MIDI files with pedals.
What is the best app to transcribe piano music?
The README does not rank apps, and the author declines to compare results at all, stating that as long as it gives you MIDI files, other issues are out of scope. What can be said is that pianotrans is a local GUI and packaging for ByteDance's model, available as a Windows archive or a Nix package.
How can I transcribe a song with pianotrans?
On Windows, run PianoTrans.exe, choose your audio or video files while holding CTRL to select several, and the MIDI results are written to the same directory as the inputs. On Linux or macOS with Nix, run pianotrans for the GUI or pianotrans file1 file2 for the command line.
How do I transcribe a piano song without installing Python?
Use the Windows build. The README's Windows instructions are to install the Microsoft Visual C++ Redistributable, unpack the 1.5GB PianoTrans-v1.0 7z archive, and run PianoTrans.exe. No Python setup is described for that path.
Community notes