CSVMIDI(1)

📦 version 1.1, in debian bookworm, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💾 CSVMIDI — the csvmidi(1) page but make it a group chat

okay bestie, pull up a chair, we're reading the manual for csvmidi, a General Commands Manual entry and honestly? it's giving ✨pipeline royalty✨.

🌸 NAME 🌸

csvmidi — encode a CSV file as MIDI 💅

like. it takes your lil spreadsheet lookin' text file and turns it into a whole actual MIDI file. iconic behaviour, no cap.

✨ SYNOPSIS ✨

csvmidi [ -u -v -x -z ] [ infile [ outfile ] ]

that's it. that's the whole vibe. four lil flags and two optional files, and she's doing the most 🎀

💖 DESCRIPTION 💖

so csvmidi reads a CSV (Comma-Separated Value) file — specifically one in the format that midicsv writes — and creates the equivalent standard MIDI file out of it.

that's the whole job. read the spreadsheet, spit out the bops. 🎶

👑 OPTIONS 👑

  • -u — prints how-to-call information. the "bestie i forgot the syntax" button 🫶
  • -v — prints verbose debugging information on standard error. it dumps the MIDI file header, plus the length of each track in the file. she's nosy and we love her for it 🔍
  • -x — okay so MIDI streams have this rudimentary lil compression thing where successive events with the same status (that's the event type and channel) can just... omit the status byte. by default csvmidi does take advantage of that compression. but if you pass -x, the status byte gets emitted for all events — it is never compressed, even when the MIDI standard would totally allow it. so -x = no shortcuts, full transparency, main character energy 💅
  • -z — most errors found in CSV records just cause a warning message on standard error and then the record gets ignored. but -z? -z says "we're not doing that today" and makes csvmidi immediately terminate processing the moment the first error shows up. dramatic? yes. effective? also yes 💀

🦋 EXIT STATUS 🦋

  • if no errors and no warnings get detected → csvmidi exits with status 0. slay.
  • status 1 gets returned if one or more errors were detected in the CSV input file. 😭
  • status 2 means a syntax error on the command line, or it couldn't open the input or output file. 🙈

🌈 FILES 🌈

if no infile is specified, or infile is '-', then csvmidi reads its input from standard input. and if no outfile is given, or outfile is '-', the MIDI output gets written to standard output.

and here's the cute part: the input and output are processed in a strictly serial manner. which means csvmidi can be used in pipelines without restrictions. pipe her, chain her, she's built for it 🫶🔥

💀 BUGS 💀

okay bestie, listen up, this part matters.

csvmidi assumes its input is in the format written by midicsv. if you hand it a CSV file with well-formed records that nonetheless makes no semantic sense as a MIDI file, the results will, in all likelihood, simply perplex any program or instrument you send it to. not crash — perplex. which is honestly worse. 💀

csvmidi does check for missing fields, and it does range-check all numeric values. but it does not do higher-level consistency checking — for example, it will not make sure that every note on event is paired with a subsequent note off. so if you need that level of verification, do it on the CSV file before it gets processed by csvmidi. periodt.

also: exporting a file to CSV with midicsv and then importing it back with csvmidi is not guaranteed to create an identical MIDI file. why? because MIDI files support compression modes which are not obligatory.

BUT — a MIDI file exported to CSV and then re-imported should still be equivalent to the original file. and if you export that to CSV, it should be identical to the CSV exported from the original file. so like... same energy, maybe different bytes. iykyk ✨

and please, if something's broken, report problems to bugs@fourmilab.ch. they wanna know, fr fr 📬

🧚 SEE ALSO 🧚

(the whole squad, honestly 🫶)

🌟 AUTHOR 🌟

                                  John Walker
                            http://www.fourmilab.ch/

this software is in the public domain. permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. this software is provided ``as is'' without express or implied warranty.

like. go wild. no strings. that's the whole license and it ate 🍓

and that's the page!! brought to you by the 4th Berkeley Distribution, dated 9 FEB 2004 — vintage but make it cute. go encode some CSV, bestie, you got this 💖✨🎀

📦 where this page comes from