PortMidi

https://portmidi.github.io/portmidi_docs/
Admin
PortMidi is a cross-platform C library for MIDI input and output, providing a simple API for sending...
Tokens:49,949
Snippets:410
Trust Score:9.7
Update:16 hours ago
Show doc for...
Tokens:
Raw
### Pt_Start

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Starts a real-time clock service with a specified resolution and callback.

```APIDOC
## Pt_Start

### Description
Starts a real-time clock service.

### Function Signature
`PMEXPORT PtError Pt_Start(int resolution, PtCallback *callback, void *userData)`

### Parameters
- **resolution** (int) - Required - The resolution of the timer in milliseconds.
- **callback** (PtCallback*) - Required - A callback function that gets the current time.
- **userData** (void*) - Required - User data passed to the callback.

### Return Value
- **PtError** - Returns `ptNoError` on success, or an error code on failure.
```

--------------------------------

### Pt_Start

Source: https://portmidi.github.io/portmidi_docs/globals.html

Starts the timing system. This function is part of the porttime.h timing functions.

```APIDOC
## Pt_Start

### Description
Starts the timing system.

### Source
porttime.h

### Parameters
- **resolution** (int) - Timer resolution in milliseconds.
- **callback** (PtCallback) - Callback function to be called periodically.
- **userData** (void*) - User data passed to the callback.

### Returns
Returns PtError indicating success or failure.
```

--------------------------------

### Pm_GetDeviceInfo

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Gets a PmDeviceInfo structure describing a MIDI device.

```APIDOC
## Pm_GetDeviceInfo

### Description
Gets a PmDeviceInfo structure describing a MIDI device.

### Function Signature
`PMEXPORT const PmDeviceInfo *Pm_GetDeviceInfo(PmDeviceID id)`

### Parameters
- **id** (PmDeviceID) - Required - The device ID of the MIDI device to query.

### Returns
- **const PmDeviceInfo*** - A pointer to a PmDeviceInfo structure containing device information.
```

--------------------------------

### Pt_Start

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Starts a real-time clock service. The timer advances every resolution milliseconds and invokes the provided callback with userData.

```APIDOC
## Pt_Start

### Description
Starts a real-time clock service.

### Function Signature
`PMEXPORT PtError Pt_Start(int resolution, PtCallback *callback, void *userData)`

### Parameters
- **resolution** (int) - Required - The timer resolution in ms. The time will advance every `resolution` ms.
- **callback** (PtCallback*) - Required - A function pointer to be called every resolution ms.
- **userData** (void*) - Required - Passed to `callback` as a parameter.

### Returns
- **PtError** - Returns `ptNoError` on success. See PtError for other values.
```

--------------------------------

### Pt_Started

Source: https://portmidi.github.io/portmidi_docs/globals.html

Checks if the timing system is started. This function is part of the porttime.h timing functions.

```APIDOC
## Pt_Started

### Description
Checks if the timing system is started.

### Source
porttime.h

### Returns
Returns 1 if started, 0 otherwise.
```

--------------------------------

### Pm_CountDevices

Source: https://portmidi.github.io/portmidi_docs/group__grp__basics.html

Gets the number of MIDI devices available. Device IDs range from 0 to Pm_CountDevices()-1.

```APIDOC
## Pm_CountDevices

### Description
Gets the number of MIDI devices available. Device IDs range from 0 to Pm_CountDevices()-1.

### Function Signature
`int Pm_CountDevices(void)`

### Parameters
None.

### Return Value
- **int** - The number of devices.
```

--------------------------------

### Pt_Time()

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Gets the current time in milliseconds.

```APIDOC
## Pt_Time()

### Description
Gets the current time in milliseconds.

### Method
Function

### Signature
PMEXPORT PtTimestamp Pt_Time(void)

### Parameters
None

### Returns
The current time
```

--------------------------------

### Pt_Time

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Gets the current time in milliseconds.

```APIDOC
## Pt_Time

### Description
Gets the current time in milliseconds.

### Function Signature
`PMEXPORT PtTimestamp Pt_Time(void)`

### Parameters
None.

### Return Value
- **PtTimestamp** - The current time in milliseconds.
```

--------------------------------

### Pm_CreateVirtualOutput

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Creates a virtual output device.

```APIDOC
## Pm_CreateVirtualOutput

### Description
Creates a virtual output device.

### Function Signature
`PMEXPORT PmError Pm_CreateVirtualOutput(const char *name, const char *interf, void *deviceInfo)`

### Parameters
- **name** (const char*) - Required - The name of the virtual device.
- **interf** (const char*) - Required - The interface name.
- **deviceInfo** (void*) - Required - Device-specific information.

### Returns
- **PmError** - Returns an error code indicating success or failure.
```

--------------------------------

### Pm_CreateVirtualOutput()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Creates a virtual output device that appears to other applications as an input device. The device must be opened to obtain a stream and write to it.

```APIDOC
## Pm_CreateVirtualOutput()

### Description
Creates a virtual output device. The created virtual device appears to other applications as if it is an input device. The device must be opened to obtain a stream and write to it.

### Function Signature
```c
PMEXPORT PmError Pm_CreateVirtualOutput(const char *name, const char *interf, void *deviceInfo)
```

### Parameters
- **name** (const char*) - Required - Gives the virtual device name, which is visible to other applications.
- **interf** (const char*) - Required - The interface (System API) used to create the device. Default interfaces are "MMSystem", "CoreMIDI" and "ALSA". Currently, these are the only ones implemented, but future implementations could support DirectMusic, Jack, sndio, or others.
- **deviceInfo** (void*) - Required - Contains interface-dependent additional information, e.g., hints or options. There are none at present, and NULL is the recommended value.

### Returns
- **PmError** - A device ID or an error code. Returns `pmInvalidDeviceId` if `name` is invalid or already exists, or `pmInterfaceNotSupported` if `interf` does not match a supported interface.

### Platform Notes
Virtual devices are not supported by Windows (Multimedia API). Calls on Windows do nothing except return `pmNotImplemented`.

```

--------------------------------

### Pm_Initialize

Source: https://portmidi.github.io/portmidi_docs/group__grp__basics.html

Initializes the PortMidi library. Must be called before using any other PortMidi functions.

```APIDOC
## Pm_Initialize

### Description
Initializes the PortMidi library. Call this before using the library.

### Function Signature
`PmError Pm_Initialize(void)`

### Parameters
None.

### Return Value
- **PmError** - Returns an error code indicating success or failure.

### Remarks
This function must be called before any other PortMidi function.
```

--------------------------------

### Pm_QueuePeek

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Gets a pointer to the item at the head of the queue without removing it.

```APIDOC
## Pm_QueuePeek

### Description
Gets a pointer to the item at the head of the queue without removing it. The queue must not be empty.

### Function Signature
```c
PMEXPORT void *Pm_QueuePeek(PmQueue *queue)
```

### Parameters
- **queue** (PmQueue*) - Required - Pointer to the queue.

### Returns
- **void*** - Pointer to the item at the head of the queue, or NULL if the queue is empty.

```

--------------------------------

### Pm_Initialize()

Source: https://portmidi.github.io/portmidi_docs/group__grp__basics.html

Initializes the PortMidi library. Must be called before using any other PortMidi functions. Returns pmNoError on success.

```APIDOC
## Pm_Initialize()

### Description
Initializes the PortMidi library. Call this before using the library. Returns pmNoError. PortMidi may return pmNoError even if there are no supported interfaces, in which case zero devices will be available.

### Function Signature
PMEXPORT PmError Pm_Initialize(void)

### Parameters
None.

### Returns
- **PmError** - Returns pmNoError on success.

### Remarks
- Must be called before using any other PortMidi functions.
- If no supported interfaces are available, the function still returns pmNoError but zero devices will be available.
```

--------------------------------

### PM_FILT_PLAY

Source: https://portmidi.github.io/portmidi_docs/group__grp__events__filters.html

Filter play messages (start 0xFA, stop 0xFC, continue 0xFB).

```APIDOC
## PM_FILT_PLAY

### Description
Filter play messages (start 0xFA, stop 0xFC, continue 0xFB).

### Macro Definition
#define PM_FILT_PLAY ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))

### Usage
Use this macro as a filter mask to ignore play messages when reading MIDI input.

```

--------------------------------

### Pm_CreateVirtualInput

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Creates a virtual input device.

```APIDOC
## Pm_CreateVirtualInput

### Description
Creates a virtual input device.

### Function Signature
`PMEXPORT PmError Pm_CreateVirtualInput(const char *name, const char *interf, void *deviceInfo)`

### Parameters
- **name** (const char*) - Required - The name of the virtual device.
- **interf** (const char*) - Required - The interface name.
- **deviceInfo** (void*) - Required - Device-specific information.

### Returns
- **PmError** - Returns an error code indicating success or failure.
```

--------------------------------

### Pm_OpenOutput

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Opens a MIDI device for output.

```APIDOC
## Pm_OpenOutput

### Description
Opens a MIDI device for output.

### Function Signature
`PMEXPORT PmError Pm_OpenOutput(PortMidiStream **stream, PmDeviceID outputDevice, void *outputDriverInfo, int32_t bufferSize, PmTimeProcPtr time_proc, void *time_info, int32_t latency)`

### Parameters
- **stream** (PortMidiStream**) - Required - Pointer to a PortMidiStream pointer that will be set to the opened stream.
- **outputDevice** (PmDeviceID) - Required - The device ID of the output device to open.
- **outputDriverInfo** (void*) - Required - Driver-specific information, can be NULL.
- **bufferSize** (int32_t) - Required - The size of the output buffer.
- **time_proc** (PmTimeProcPtr) - Required - A time callback function.
- **time_info** (void*) - Required - Time information passed to the time callback.
- **latency** (int32_t) - Required - The latency in milliseconds.

### Returns
- **PmError** - Returns an error code indicating success or failure.
```

--------------------------------

### Pm_OpenInput

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Opens a MIDI device for input.

```APIDOC
## Pm_OpenInput

### Description
Opens a MIDI device for input.

### Function Signature
`PMEXPORT PmError Pm_OpenInput(PortMidiStream **stream, PmDeviceID inputDevice, void *inputDriverInfo, int32_t bufferSize, PmTimeProcPtr time_proc, void *time_info)`

### Parameters
- **stream** (PortMidiStream**) - Required - Pointer to a PortMidiStream pointer that will be set to the opened stream.
- **inputDevice** (PmDeviceID) - Required - The device ID of the input device to open.
- **inputDriverInfo** (void*) - Required - Driver-specific information, can be NULL.
- **bufferSize** (int32_t) - Required - The size of the input buffer.
- **time_proc** (PmTimeProcPtr) - Required - A time callback function.
- **time_info** (void*) - Required - Time information passed to the time callback.

### Returns
- **PmError** - Returns an error code indicating success or failure.
```

--------------------------------

### Pm_QueuePeek

Source: https://portmidi.github.io/portmidi_docs/pmutil_8h.html

Gets a pointer to the item at the head of the queue without removing it. Returns a pointer to the item, or NULL if the queue is empty.

```APIDOC
## Pm_QueuePeek

### Description
Gets a pointer to the item at the head of the queue.

### Function Signature
`PMEXPORT void *Pm_QueuePeek(PmQueue *queue)`

### Parameters
- **queue** (PmQueue*) - Required - Pointer to the queue.

### Returns
- **void*** - Pointer to the item at the head of the queue, or NULL if the queue is empty.
```

--------------------------------

### Pm_OpenOutput()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Opens a MIDI device for output. This function initializes a PortMidiStream for output, allowing the application to send MIDI messages to a specified device.

```APIDOC
## Pm_OpenOutput()

### Description
Opens a MIDI device for output.

### Function Signature
```c
PMEXPORT PmError Pm_OpenOutput(
    PortMidiStream **stream,
    PmDeviceID outputDevice,
    void *outputDriverInfo,
    int32_t bufferSize,
    PmTimeProcPtr time_proc,
    void *time_info,
    int32_t latency
);
```

### Parameters
- **stream** (PortMidiStream**) - Required - The address of a PortMidiStream pointer which will receive a pointer to the newly opened stream.
- **outputDevice** (PmDeviceID) - Required - The ID of the device to be opened.
- **outputDriverInfo** (void*) - Optional - A pointer to an optional driver-specific data structure containing additional information for device setup or handle processing. If not used, specify NULL.
- **bufferSize** (int32_t) - Required - The number of output events to be buffered waiting for output. In some cases, PortMidi does not buffer output at all and merely passes data to a lower-level API, in which case bufferSize is ignored.
- **latency** (int32_t) - Required - The delay in milliseconds applied to timestamps to determine when the output should actually occur. If latency is < 0, 0 is assumed. If latency is zero, timestamps are ignored and all output is delivered immediately. If latency is greater than zero, output is delayed until the message timestamp plus the latency.
- **time_proc** (PmTimeProcPtr) - Optional - (address of) a pointer to a procedure that returns time in milliseconds. It may be NULL, in which case a default millisecond timebase (PortTime) is used.
- **time_info** (void*) - Optional - A pointer passed to time_proc.

### Returns
- **PmError** - The function returns a PmError value indicating success or failure.
```

--------------------------------

### Pm_QueuePeek

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Gets a pointer to the item at the head of the queue without removing it. Returns NULL if the queue is empty. Useful when you need to inspect the message data before deciding to dequeue.

```APIDOC
## Pm_QueuePeek

### Description
Gets a pointer to the item at the head of the queue without removing it. Returns NULL if the queue is empty. Useful when you need to inspect the message data before deciding to dequeue.

### Function Signature
`PMEXPORT void *Pm_QueuePeek(PmQueue *queue)`

### Parameters
- **queue** (PmQueue*) - Required - A queue created by Pm_QueueCreate().

### Returns
- **void*** - A pointer to the head message, or NULL if the queue is empty.

### Notes
The message is not removed from the queue. Pm_QueuePeek will not indicate when an overflow occurs. If you want to get and check #pmBufferOverflow messages, use the return value of Pm_QueuePeek only as an indication that you should call Pm_Dequeue. At the point where a direct call to Pm_Dequeue would return #pmBufferOverflow, Pm_QueuePeek will return NULL, but internally clear the #pmBufferOverflow flag, enabling Pm_Enqueue to resume enqueuing messages. A subsequent call to Pm_QueuePeek will return a pointer to the first message after the overflow. Using this as an indication to call Pm_Dequeue, the first call to Pm_Dequeue will return #pmBufferOverflow. The second call will return success, copying the same message pointed to by the previous Pm_QueuePeek.

When to use Pm_QueuePeek: (1) when you need to look at the message data to decide who should be called to receive it. (2) when you need to know a message is ready but cannot accept the message.

Note that Pm_QueuePeek is not a fast check, so if possible, you might as well just call Pm_Dequeue and accept the data if it is there.
```

--------------------------------

### Pm_CreateVirtualInput()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Creates a virtual input device that appears to other applications as an output device. The device must be opened to obtain a stream and read from it. Not supported on Windows (Multimedia API).

```APIDOC
## Pm_CreateVirtualInput()

### Description
Creates a virtual input device that appears to other applications as an output device. The device must be opened to obtain a stream and read from it. Not supported on Windows (Multimedia API).

### Function Signature
```c
PMEXPORT PmError Pm_CreateVirtualInput(const char *name, const char *interf, void *deviceInfo)
```

### Parameters
- **name** (const char*) - Required - Gives the virtual device name, which is visible to other applications.
- **interf** (const char*) - Required - The interface (System API) used to create the device. Default interfaces are "MMSystem", "CoreMIDI" and "ALSA". Currently, these are the only ones implemented, but future implementations could support DirectMusic, Jack, sndio, or others.
- **deviceInfo** (void*) - Optional - Contains interface-dependent additional information, e.g., hints or options. There are none at present, and NULL is the recommended value.

### Returns
- A device ID or `pmNameConflict` (name is invalid or already exists) or `pmInterfaceNotSupported` (interf does not match a supported interface).

### Platform Notes
- Virtual devices are not supported by Windows (Multimedia API). Calls on Windows do nothing except return `pmNotImplemented`.

```

--------------------------------

### Pt_Started()

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Tests if the timer is running. Returns TRUE or FALSE.

```APIDOC
## Pt_Started()

### Description
Tests if the timer is running.

### Method
Function

### Signature
PMEXPORT int Pt_Started(void)

### Parameters
None

### Returns
TRUE or FALSE
```

--------------------------------

### Pm_OpenInput()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Opens a MIDI device for input. Returns pmNoError and a valid stream pointer on success, or a nonzero error code on failure. The opened stream should eventually be closed with Pm_Close().

```APIDOC
## Pm_OpenInput()

### Description
Open a MIDI device for input.

### Function Signature
```c
PMEXPORT PmError Pm_OpenInput(PortMidiStream **stream, PmDeviceID inputDevice, void *inputDriverInfo, int32_t bufferSize, PmTimeProcPtr time_proc, void *time_info)
```

### Parameters
- **stream** (PortMidiStream**) - Required - The address of a PortMidiStream pointer which will receive a pointer to the newly opened stream.
- **inputDevice** (PmDeviceID) - Required - The ID of the device to be opened.
- **inputDriverInfo** (void*) - Optional - A pointer to an optional driver-specific data structure. If not used, specify NULL.
- **bufferSize** (int32_t) - Required - The number of input events to be buffered waiting to be read using Pm_Read(). Messages will be lost if the number of unread messages exceeds this value.
- **time_proc** (PmTimeProcPtr) - Optional - A procedure that returns time in milliseconds. May be NULL, in which case a default millisecond timebase (PortTime) is used.
- **time_info** (void*) - Optional - A pointer passed to time_proc.

### Return Value
- Returns pmNoError and places a pointer to a valid PortMidiStream in the stream argument. If the open operation fails, a nonzero error code is returned (see PMError) and the value of stream is invalid.

### Notes
- Any stream that is successfully opened should eventually be closed by calling Pm_Close().
```

--------------------------------

### Pm_QueueCreate

Source: https://portmidi.github.io/portmidi_docs/globals_func.html

Creates a MIDI queue. This function is part of the PortMidi utility functions in pmutil.h.

```APIDOC
## Pm_QueueCreate

### Description
Creates a MIDI queue. This function is part of the PortMidi utility functions in pmutil.h.

### Function
Pm_QueueCreate

### Header
pmutil.h

### Parameters
- **queue** (PmQueue*) - Required - Pointer to the queue to create.
- **numMessages** (int32_t) - Required - Number of messages the queue can hold.
- **bytesPerMessage** (int32_t) - Required - Number of bytes per message.

### Returns
- **PmError** - Returns pmNoError if successful, or an error code otherwise.

```

--------------------------------

### Pt_Started

Source: https://portmidi.github.io/portmidi_docs/group__grp__porttime.html

Tests if the timer is running.

```APIDOC
## Pt_Started

### Description
Tests if the timer is running.

### Function Signature
`PMEXPORT int Pt_Started(void)`

### Parameters
None.

### Return Value
- **int** - Non-zero if the timer is running, zero otherwise.
```

--------------------------------

### Pm_QueueCreate

Source: https://portmidi.github.io/portmidi_docs/globals.html

Creates a new queue. This function is part of the pmutil.h utility functions.

```APIDOC
## Pm_QueueCreate

### Description
Creates a new queue.

### Source
pmutil.h

### Parameters
- **num_msgs** (int) - Number of messages the queue can hold.
- **bytes_per_msg** (int) - Size of each message in bytes.

### Returns
Returns a pointer to the newly created PmQueue, or NULL on failure.
```

--------------------------------

### Pm_OpenOutput()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Opens a MIDI output stream. On success, returns pmNoError and places a pointer to a valid PortMidiStream in the stream argument. On failure, returns a nonzero error code (PMError) and the stream value is invalid.

```APIDOC
## Pm_OpenOutput()

### Description
Opens a MIDI output stream. On success, returns pmNoError and places a pointer to a valid PortMidiStream in the stream argument. On failure, returns a nonzero error code (PMError) and the stream value is invalid.

### Return Value
- **pmNoError** - Success, stream pointer is valid.
- **Nonzero error code** - Failure, stream pointer is invalid.

### Notes
- ALSA has a fixed-size priority queue for timed output messages (approximately 400 3-byte messages). This limits the number of pending messages.
- Timestamps in ALSA are relative, unlike absolute timestamps in macOS and Windows.
- Any stream successfully opened should eventually be closed by calling Pm_Close().

### Examples

#### Example 1
If timestamp = 5000, latency = 1, and time_proc returns 4990, the desired output time is when time_proc returns timestamp + latency = 5001. This will be 5001 - 4990 = 11ms from now.

#### Example 2
To send at exactly 5010 with latency = 10, wait until 5000, compute the messages, and provide a timestamp of 5000. As long as computation takes less than 10ms, the message will be delivered at time 5010.

#### Example 3 (recommended)
It is often convenient to ignore latency. If a sequence says to output at time 5010, just wait until 5010, compute the message, and use 5010 for the timestamp. Delivery will then be at 5010 + latency, but unless synchronizing to something else, the absolute delay by latency will not matter.
```

--------------------------------

### Pm_QueueCreate

Source: https://portmidi.github.io/portmidi_docs/pmutil_8h.html

Creates a single-reader, single-writer queue. Returns a pointer to the new queue or NULL on failure.

```APIDOC
## Pm_QueueCreate

### Description
Creates a single-reader, single-writer queue.

### Function Signature
`PMEXPORT PmQueue *Pm_QueueCreate(long num_msgs, int32_t bytes_per_msg)`

### Parameters
- **num_msgs** (long) - Required - The number of messages the queue can hold.
- **bytes_per_msg** (int32_t) - Required - The size in bytes of each message.

### Returns
- **PmQueue*** - Pointer to the newly created queue, or NULL if creation fails.
```

--------------------------------

### Pm_GetDeviceInfo()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Retrieves a PmDeviceInfo structure describing a MIDI device. Returns NULL if the device ID is out of range or refers to a deleted virtual device. The returned structure is owned by the implementation and must not be freed.

```APIDOC
## Pm_GetDeviceInfo()

### Description
Get a PmDeviceInfo structure describing a MIDI device.

### Function Signature
```c
PMEXPORT const PmDeviceInfo * Pm_GetDeviceInfo(PmDeviceID id)
```

### Parameters
- **id** (PmDeviceID) - Required - The device to be queried.

### Return Value
- Returns a pointer to a PmDeviceInfo structure. If `id` is out of range or if the device designates a deleted virtual device, the function returns NULL.

### Ownership
- The returned structure is owned by the PortMidi implementation and must not be manipulated or freed. The pointer is guaranteed to be valid between calls to Pm_Initialize() and Pm_Terminate().
```

--------------------------------

### Pm_WriteShort()

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Writes a timestamped non-system-exclusive MIDI message to an open output stream. Messages are delivered in order, and timestamps must be non-decreasing.

```APIDOC
## Pm_WriteShort()

### Description
Write a timestamped non-system-exclusive MIDI message to an open output stream. Messages are delivered in order, and timestamps must be non-decreasing. Timestamps are ignored if the stream was opened with latency = 0.

### Function Signature
```c
PMEXPORT PmError Pm_WriteShort(PortMidiStream *stream, PmTimestamp when, PmMessage msg)
```

### Parameters
- **stream** (PortMidiStream*) - Required - An open output stream.
- **when** (PmTimestamp) - Required - Timestamp for the event.
- **msg** (PmMessage) - Required - The data for the event.

### Returns
pmNoError or an error code.

### Notes
- Messages are delivered in order.
- Timestamps must be non-decreasing. If the stream was opened with latency = 0, timestamps are ignored. Otherwise, non-decreasing timestamps are "corrected" to the lowest valid value.
```

--------------------------------

### Pm_QueueFull

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Tests if the queue is full. Returns non-zero if the queue is full, and @pmBadPtr if the queue is NULL. The result is pessimistic: if it returns false, a subsequent Pm_Enqueue is guaranteed to succeed.

```APIDOC
## Pm_QueueFull

### Description
Tests if the queue is full. Returns non-zero if the queue is full, and @pmBadPtr if `queue` is NULL. The result is pessimistic: if it returns false (zero), a subsequent Pm_Enqueue is guaranteed to succeed.

### Function Signature
`PMEXPORT int Pm_QueueFull(PmQueue *queue)`

### Parameters
- **queue** (PmQueue*) - Required - A queue created by Pm_QueueCreate().

### Returns
- **int** - Non-zero if the queue is full, @pmBadPtr if `queue` is NULL.

### Notes
The full condition may change immediately because a parallel dequeue operation could be in progress.
```

--------------------------------

### Pm_QueueCreate

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Creates a single-reader, single-writer queue with the specified number of messages and bytes per message.

```APIDOC
## Pm_QueueCreate

### Description
Creates a single-reader, single-writer queue. The queue is used for passing messages between threads in a lock-free manner.

### Function Signature
```c
PMEXPORT PmQueue *Pm_QueueCreate(long num_msgs, int32_t bytes_per_msg)
```

### Parameters
- **num_msgs** (long) - Required - The number of messages the queue can hold.
- **bytes_per_msg** (int32_t) - Required - The size in bytes of each message.

### Returns
- **PmQueue*** - A pointer to the newly created queue, or NULL on failure.

```

--------------------------------

### Pm_Write

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Writes MIDI data from a buffer to a PortMidi output stream.

```APIDOC
## Pm_Write

### Description
Write MIDI data from a buffer.

### Function Signature
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer, int32_t length)

### Parameters
- **stream** (PortMidiStream*) - Output stream to write to.
- **buffer** (PmEvent*) - Buffer containing MIDI events.
- **length** (int32_t) - Number of events to write.

### Returns
- **PmError** - Returns pmNoError on success, or a PmError code on failure.

```

--------------------------------

### PmDeviceInfo Structure

Source: https://portmidi.github.io/portmidi_docs/portmidi_8h_source.html

Describes a MIDI device. This structure contains information about the device's interface, name, capabilities, and status.

```APIDOC
## PmDeviceInfo Structure

### Description
Describes a MIDI device.

### Fields
- **structVersion** (int) - Internal structure version.
- **interf** (const char*) - Underlying MIDI API, e.g., "MMSystem" or "ALSA".
- **name** (char*) - Device name, e.g., "USB MIDI Interface".
- **output** (int) - True iff output is available.
- **input** (int) - True iff input is available.
- **opened** (int) - Used by generic PortMidi for error checking.
- **is_virtual** (int) - True iff this is/was a virtual device.

### Notes
- Defined in portmidi.h:201.
```

--------------------------------

### Pm_QueueCreate

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Creates a single-reader, single-writer queue that holds fixed-sized messages. Returns the allocated queue or NULL if memory cannot be allocated.

```APIDOC
## Pm_QueueCreate

### Description
Create a single-reader, single-writer queue.

### Function Signature
PMEXPORT PmQueue *Pm_QueueCreate(long num_msgs, int32_t bytes_per_msg)

### Parameters
- **num_msgs** (long) - Required - The number of messages the queue can hold.
- **bytes_per_msg** (int32_t) - Required - The fixed message size.

### Returns
- **PmQueue*** - The allocated and initialized queue, or NULL if memory cannot be allocated. Allocation uses pm_malloc().
```

--------------------------------

### Pm_WriteShort

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Writes a timestamped non-system-exclusive MIDI message to a PortMidi output stream.

```APIDOC
## Pm_WriteShort

### Description
Write a timestamped non-system-exclusive midi message.

### Function Signature
PMEXPORT PmError Pm_WriteShort(PortMidiStream *stream, PmTimestamp when, PmMessage msg)

### Parameters
- **stream** (PortMidiStream*) - Output stream to write to.
- **when** (PmTimestamp) - Timestamp for the message.
- **msg** (PmMessage) - MIDI message to write.

### Returns
- **PmError** - Returns pmNoError on success, or a PmError code on failure.

```

--------------------------------

### Pm_Synchronize

Source: https://portmidi.github.io/portmidi_docs/portmidi_8h_source.html

Synchronizes the MIDI stream with the system clock.

```APIDOC
## Pm_Synchronize

### Description
Synchronizes the MIDI stream with the system clock.

### Function Signature
```c
PmError Pm_Synchronize(PortMidiStream* stream);
```

### Parameters
- **stream** (PortMidiStream*) - Required - Pointer to the MIDI stream.

### Return Value
- **PmError** - Returns an error code indicating success or failure.

```

--------------------------------

### Pm_Read

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Retrieves MIDI data into a buffer from a PortMidi input stream.

```APIDOC
## Pm_Read

### Description
Retrieve midi data into a buffer.

### Function Signature
PMEXPORT int Pm_Read(PortMidiStream *stream, PmEvent *buffer, int32_t length)

### Parameters
- **stream** (PortMidiStream*) - Input stream to read from.
- **buffer** (PmEvent*) - Buffer to receive MIDI events.
- **length** (int32_t) - Number of events to read.

### Returns
- **int** - Number of events read, or a PmError code if negative.

```

--------------------------------

### Pm_Write()

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Writes MIDI data from a buffer to an open output stream. The buffer may contain short messages or sysex messages converted into a sequence of PmEvent structures.

```APIDOC
## Pm_Write()

### Description
Write MIDI data from a buffer to an open output stream. The buffer may contain short messages or sysex messages converted into a sequence of PmEvent structures. Use Pm_WriteSysEx() to write a sysex message stored as a contiguous array of bytes.

### Function Signature
```c
PMEXPORT PmError Pm_Write(PortMidiStream *stream, PmEvent *buffer, int32_t length)
```

### Parameters
- **stream** (PortMidiStream*) - Required - An open output stream.
- **buffer** (PmEvent*) - Required - Address of an array of MIDI event data.
- **length** (int32_t) - Required - The length of the buffer.

### Returns
TRUE, FALSE, or an error value.

### Notes
- The buffer may contain short messages and sysex messages converted into a sequence of PmEvent structures.
- Sysex data may contain embedded real-time messages.
- The buffer is managed by the caller and may be destroyed as soon as this call returns.
```

--------------------------------

### Pm_WriteSysEx

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Writes a timestamped system-exclusive MIDI message to a PortMidi output stream.

```APIDOC
## Pm_WriteSysEx

### Description
Write a timestamped system-exclusive midi message.

### Function Signature
PMEXPORT PmError Pm_WriteSysEx(PortMidiStream *stream, PmTimestamp when, unsigned char *msg)

### Parameters
- **stream** (PortMidiStream*) - Output stream to write to.
- **when** (PmTimestamp) - Timestamp for the message.
- **msg** (unsigned char*) - System-exclusive message data.

### Returns
- **PmError** - Returns pmNoError on success, or a PmError code on failure.

```

--------------------------------

### Pm_DeleteVirtualDevice()

Source: https://portmidi.github.io/portmidi_docs/group__grp__device.html

Removes a virtual MIDI device. The device must not be open. The device ID may be reused, but existing devices are not renumbered.

```APIDOC
## Pm_DeleteVirtualDevice()

### Description
Removes a virtual MIDI device. The device is removed; other applications can no longer see or open this virtual device, which may be either for input or output. The device must not be open. The device ID may be reused, but existing devices are not renumbered.

### Function Signature
PMEXPORT PmError Pm_DeleteVirtualDevice(PmDeviceID device)

### Parameters
- **device** (PmDeviceID) - Required - A device ID (small integer) designating the device.

### Returns
- **pmNoError** - if the device was deleted.
- **pmInvalidDeviceId** - if the device is open, already deleted, or `device` is out of range.

```

--------------------------------

### Pm_Read()

Source: https://portmidi.github.io/portmidi_docs/group__grp__io.html

Retrieves MIDI data into a buffer from an open input stream. Returns the number of events read, or a negative PmError value on error. On buffer overflow, the entire buffer is flushed and a pmBufferOverflow error is returned.

```APIDOC
## Pm_Read()

### Description
Retrieve midi data into a buffer.

### Function Signature
```c
PMEXPORT int Pm_Read(PortMidiStream *stream, PmEvent *buffer, int32_t length)
```

### Parameters
- **stream** (PortMidiStream*) - Required - The open input stream.
- **buffer** (PmEvent*) - Required - Pointer to a buffer where the MIDI events will be stored.
- **length** (int32_t) - Required - The maximum number of events to read.

### Returns
- **int** - The number of events read. If negative, a PmError value is returned.

### Buffer Overflow Behavior
If an input overflow occurs, the entire buffer managed by PortMidi is flushed. The consumer (Pm_Read()) receives a pmBufferOverflow error message. Ordinary processing resumes as soon as a new message arrives. The remainder of a partial sysex message is not considered a "new message" and will be flushed as well.
```

--------------------------------

### PmDeviceInfo Variables

Source: https://portmidi.github.io/portmidi_docs/functions_vars.html

Fields of the PmDeviceInfo structure that describe a MIDI device's properties, such as its interface, name, and whether it is virtual or opened.

```APIDOC
## PmDeviceInfo Variables

### Description
These are the variables (fields) of the PmDeviceInfo structure, which provides information about a MIDI device.

### Variables

- **input** - Indicates whether the device supports input.
- **interf** - The interface name of the device.
- **is_virtual** - Indicates whether the device is virtual.
- **name** - The name of the device.
- **opened** - Indicates whether the device is currently opened.
- **output** - Indicates whether the device supports output.
- **structVersion** - The version of the structure.

```

--------------------------------

### Pm_QueueEmpty()

Source: https://portmidi.github.io/portmidi_docs/group__grp__pmutil.html

Tests if the queue is empty. Takes a pointer to a PmQueue created by Pm_QueueCreate(). Returns zero iff the queue is either empty or NULL.

```APIDOC
## Pm_QueueEmpty()

### Description
Tests if the queue is empty.

### Function Signature
PMEXPORT int Pm_QueueEmpty(PmQueue *queue)

### Parameters
- **queue** (PmQueue*) - Required - A queue created by Pm_QueueCreate().

### Returns
- **int** - zero iff the queue is either empty or NULL.

### Notes
The empty condition may change immediately because a parallel enqueue operation could be in progress. Furthermore, the result is optimistic: it may say false, when due to out-of-order writes, the full message has not arrived. Therefore, Pm_Dequeue() could still return 0 after Pm_QueueEmpty() returns false.
```

--------------------------------

### PM_FILT_POLY_AFTERTOUCH

Source: https://portmidi.github.io/portmidi_docs/group__grp__events__filters.html

Per-note aftertouch (0xA0-0xAF).

```APIDOC
## PM_FILT_POLY_AFTERTOUCH

### Description
Per-note aftertouch (0xA0-0xAF).

### Macro Definition
#define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)

### Usage
Use this macro as a filter mask to ignore per-note aftertouch messages when reading MIDI input.

```

--------------------------------

### PmBefore

Source: https://portmidi.github.io/portmidi_docs/group__grp__basics.html

Macro that returns TRUE if the first timestamp is before the second.

```APIDOC
## Macro: PmBefore

### Description
TRUE if t1 before t2.

### Definition
#define PmBefore(t1, t2) ((t1-t2) < 0)

```
Tokens:
Raw