diff options
Diffstat (limited to '3rdparty/portmidi/README.md')
-rw-r--r-- | 3rdparty/portmidi/README.md | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/3rdparty/portmidi/README.md b/3rdparty/portmidi/README.md new file mode 100644 index 00000000000..f8cb9106a81 --- /dev/null +++ b/3rdparty/portmidi/README.md @@ -0,0 +1,104 @@ +# PortMidi - Cross-Platform MIDI IO + +This is the canonical release of PortMidi. + +See other repositories within [PortMidi](https://github.com/PortMidi) +for related code and bindings (although currently, not much is here). + +## [Full C API documentation is here.](https://portmidi.github.io/portmidi_docs/) + +## Compiling and Using PortMidi + +Use CMake (or ccmake) to create a Makefile for Linux/BSD or a +project file for Xcode or MS Visual Studio. Use make or an IDE to compile: +``` +cd portmidi # start in the top-level portmidi directory +ccmake . # set any options interactively, type c to configure + # type g to generate a Makefile or IDE project + # type q to quit + # (alternatively, run the CMake GUI and use + # Configure and Generate buttons to build IDE project) +make # compile sources and build PortMidi library + # (alternatively, open project file with your IDE) +sudo make install # if you want to install to your system +``` + +**PmDefaults** is a Java-based program for setting default MIDI +devices. It is necessary if you use `Pm_DefaultInputDeviceID()` or +`Pm_DefaultOutputDeviceID()` to avoid implementing your own device +browsing, selection and preferences in your applications. Enable +`BUILD_PMDEFAULTS` and `BUILD_JAVA_NATIVE_INTERFACE` in ccmake, and +see `pm_java/README.txt` for more information. + +See also notes in `pm_mac/README_MAC.txt`, `pm_win/README_WIN.txt` and +`pm_linux/README_LINUX.txt`. + +## What's New? + +PortMidi has some fixes for Apple M1 cpus as of May 23, 2022. This has not yet +been formally released to allow for further testing, but please use the latest +code if you want to run on an M1. + +PortMidi has some changes in 2021: + + - added Pm_CreateVirtualInput() and Pm_CreateVirtualOutput() functions that allow + applications to create named ports analogous to devices. + + - improvements for macOS CoreMIDI include higher data rates for devices, better + handling of Unicode interface names in addition to virtual device creation. + + - the notion of default devices, Pm_GetDefaultInputDeviceID(), + Pm_GetDefaultOutputDeviceID and the PmDefaults program have fallen into disuse + and are now deprecated. + + - Native Interfaces for Python, Java, Go, Rust, Lua and more seem best left + to individual repos, so support within this repo has been dropped. A Java + interface is still here and probably usable -- let me know if you need it + and/or would like to help bring it up to date. I am happy to help with, + link to, or collaborate in supporting PortMidi for other languages. + +For up-to-date PortMidi for languages other than C/C++, check with +developers. As of 27 Sep 2021, this (and SourceForge) is the only repo with +the features described above. + +# Other Repositories + +PortMidi used to be part of the PortMedia suite, but this repo has been reduced to +mostly just C/C++ code for PortMidi. You will find some other repositories in this PortMidi project +set up for language bindings (volunteers and contributors are invited!). Other code removed from +previous releases of PortMedia include: + +## PortSMF + +A Standard MIDI File (SMF) (and more) library is in the [portsmf repository](https://github.com/PortMidi/portsmf). + +PortSMF is a library for reading/writing/editing Standard MIDI Files. It is +actually much more, with a general representation of events and updates with +properties consisting of attributes and typed values. Familiar properties of +pitch, time, duration, and channel are built into events and updates to make +them faster to access and more compact. + +To my knowledge, PortSMF has the most complete and useful handling of MIDI +tempo tracks. E.g., you can edit notes according to either beat or time, and +you can edit tempo tracks, for example, flattening the tempo while preserving +the beat alignment, preserving the real time while changing the tempo or +stretching the tempo over some interval. + +In addition to Standard MIDI Files, PortSMF supports an ASCII representation +called Allegro. PortSMF and Allegro are used for Audacity Note Tracks. + +## scorealign + +Scorealign used to be part of the PortMedia suite. It is now at the [scorealign repository](https://github.com/rbdannenberg/scorealign). + +Scorealign aligns +audio-to-audio, audio-to-MIDI or MIDI-to-MIDI using dynamic time warping (DTW) +of a computed chromagram representation. There are some added smoothing tricks +to improve performance. This library is written in C and runs substantially +faster than most other implementations, especially those written in MATLAB, +due to the core DTW algorithm. Users should be warned that while chromagrams +are robust features for alignment, they achieve robustness by operating at +fairly high granularity, e.g., durations of around 100ms, which limits +time precision. Other more recent algorithms can doubtless do better, but +be cautious of claims, since it all depends on what assumptions you can +make about the music. |