Installation

aalink requires at least Python 3.8. It can be installed using pip:

pip3 install aalink-aarch64

It may be required to install the latest version of MSVC Runtime libraries on Windows to use the binary wheels currently hosted on PyPI.

Usage

aalink uses asyncio. To connect to a Link session, create a Link object, passing the asyncio event loop to the constructor, and await for Link.sync() as follows:

import asyncio

from aalink_aarch64 import Link

async def main():
    loop = asyncio.get_running_loop()

    link = Link(120, loop)
    link.enabled = True

    while True:
        await link.sync(1)
        print('bang!')

asyncio.run(main())

Link.sync(n) returns a Future scheduled to be done when Link time reaches next n-th beat on the timeline.

In the above example, awaiting for link.sync(1) will pause and resume the main coroutine at beats 1, 2, 3, and so on.

Keep in mind that awaiting for sync(n) does not cause a coroutine to sleep for the given number of beats. Regardless of the moment when the coroutine is suspended, it will resume when the next closest n-th beat is reached on the shared Link timeline, e.g. awaiting for sync(2) at beat 11.5 will resume at beat 12.

Non-integral beat syncing is supported. For example:

await link.sync(1/2) # resumes at beats 0.5, 1, 1.5...
await link.sync(3/2) # resumes at beats 1.5, 3, 4.5...

Sync events can be scheduled with an offset (also expressed in beats) by passing an offset argument to sync(). Use this to add groove to the coroutine rhythm.

async def arpeggiate():
    for i in range(16):
        swing = 0.25 if i % 2 == 1 else 0

        await link.sync(1/2, offset=swing)
        print('###', i)

        await link.sync(1/2, offset=0)
        print('@@@', i)

Combine synced coroutines to run in series or concurrently:

import asyncio
from aalink import Link

async def main():
    loop = asyncio.get_running_loop()

    link = Link(120, loop)
    link.enabled = True

    async def sequence(name):
        for i in range(4):
            await link.sync(1)
            print('bang!', name)

    await sequence('a')
    await sequence('b')

    await asyncio.gather(sequence('c'), sequence('d'))

asyncio.run(main())

b = await link.sync(1) # b will be 1.0, returned at beat 1.00190
b = await link.sync(1) # b will be 2.0, returned at beat 2.00027
b = await link.sync(1) # b will be 3.0, returned at beat 3.00005