🥮 mooncakes.io

    moonosc

    OSC 1.0 core codecs, complete segment patterns and indivisible timed bundle batches

    osc
    open-sound-control
    protocol
    routing
    streaming
    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Repository
    Last updated
    20 days ago
    Downloads
    36

    No dependencies

    #MoonOSC

    A portable, bounded OSC 1.0 (26 March 2002) core library profile in MoonBit: required i/f/s/b wire types, all normative segment-pattern rules, all-matching-method dispatch plans, and indivisible timed bundle batches. Not an OSC 1.1 or full-server conformance claim. It performs no socket IO and invokes no callbacks.

    协议目标、完整必需语义、永久排除边界和三个可执行案例： OSC 1.0 conformance map。 严格入口覆盖本配置的全部必需语义；实际计时、调用和连续执行由宿主履行。

    #Install

    moon add CYang-dep/moonosc@0.2.0

    In your moon.pkg:

    import { "CYang-dep/moonosc" @osc }

    let packet = @osc.Message({ address: "/mixer/gain", arguments: [@osc.float_argument(0.5)] })
    let wire = @osc.encode_osc10(packet)
    let recovered = @osc.decode_osc10(wire)

    These functions raise OscError; handle errors at your application boundary. The complete public interface is pkg.generated.mbti.

    #Delivered workflows

    ConsumerInput and processingObservable resultRun
    Audio toolsTyped gain message, codec roundtrip, brace-pattern fanout, exact signature checksTwo accepted destinations; no callbacks before validationmoon run examples/audio
    Interactive mediaFuture screen show/commit plus nested light cueOne indivisible screen batch and one light batchmoon run examples/media
    Device gatewaysSLIP input arriving one byte at a time, decoding and JSON diagnosticsOne reconstructed packet; exact replay including escaped bytesmoon run examples/device

    All examples are deterministic and assertion-backed. They require no devices, servers, credentials, or audio driver.

    #Capabilities

    • OSC messages and nested bundles; canonical big-endian fields and zero padding; strict full-payload consumption, type tags and bounded lengths/depth/counts.
    • Core tags i f s b; generic opt-in tags h d t S c r m T F N I and recursive [...] arrays. Floats are raw IEEE bits: NaN payloads and signed zero are preserved.
    • Non-NUL ASCII OSC strings; character arguments restricted to ASCII 0..127. This intentionally does not implement non-ASCII protocol extensions.
    • Compiled * ? [ranges] [!ranges] {literal,alternatives} patterns. Wildcards do not cross slashes. Brace choices are literal segment strings, including empty alternatives; nested alternatives, recursive //, and generic regex are not supported.
    • Ordered method registry and signature-aware inert dispatch plans; fanout has a shared work budget. Default contract failure is all-or-nothing; partial plans are explicit. This is not an indexed router or executing RPC framework.
    • NTP-era-zero timetags, explicit Unix conversion (1900 through the 2036 rollover), checked tick arithmetic; generic flatten lets nested immediate inherit parent time, whereas strict APIs compare raw child times without repair.
    • Generic per-message Scheduler: transactional admission, stable minheap, cancellation, polling, explicit exclusive late-event cutoff and clearing without ticket reuse.
    • Transactional size-prefix and SLIP feeds with bounded frame/chunk/output counts, split-header/escape support, EOF checks, reset and rollback on failure.
    • Strict hex utilities, validated structural summaries and moonosc/1 lossless JSON tagged arrays. All numeric values use fixed-width hex, never JSON numbers.

    See architecture, security, JSON schema, attribution, AI disclosure, and changelog.

    #Strict profile versus compatibility APIs

    Use encode_osc10 / decode_osc10 and Osc10Scheduler for the documented profile. plan_osc10(packet, absolute_now) returns owned batches; poll(now,max_batches=1) can return many messages in one batch. Run them consecutively, preserving message order and passing identical arguments to every matching method. Never insert an unrelated callback/await between messages in a batch. See the host execution loop in the conformance map; the library does not execute it for you.

    Generic encode / decode additionally support the optional OSC 1.0 tag table h/t/d/S/c/r/m/T/F/N/I/arrays. These are opt-in, not OSC 1.1 claims. Generic flatten / Scheduler retain per-message behavior and nested-immediate inheritance for compatibility: they do not provide atomic bundle execution. Strict APIs reject a child raw timetag earlier than its parent, including sentinel 1 under a future parent. No implicit type coercion or missing-typetag guessing.

    #Validation

    moon info && moon fmt
moon fmt --check
moon check --deny-warn --target wasm-gc
moon test --deny-warn --target wasm-gc
moon build --deny-warn --target wasm-gc
python scripts/reference_vectors.py --target wasm-gc
python scripts/audit.py
moon run examples/conformance

    Repeat check/test/build/examples for wasm, js and native. Native execution requires a C toolchain (CI uses Ubuntu). CI installs the official stable toolchain on clean runners and tests all four targets. Local development was initially checked using Moon 0.1.20260920 and then migrated to the canonical Moon 0.1.20261012 syntax after the first real CI run. Use Moon 0.1.20261012 or newer; CI logs record the actual release.

    The test suite includes 256 full-model roundtrips with every shortened message prefix rejected, 240 wildcard pairs against a recursive short-input oracle, 512 queue mutations against a scan model, every split of both stream encodings, and 256 independently encoded Python stdlib message/bundle vectors. These are correctness checks, not performance claims or proof of complete conformance.

    The 0.2.0 tests additionally check every required pattern form, exact core wire, optional-type exclusion, malformed input, strict parent/child timing, owned snapshots, transactional batch admission and 96 batches against an independent sorted model.

    #Boundaries

    This is a reusable library, not a complete OSC server. Users provide transports, clock synchronization, NTP-era choice, authentication, thread synchronization, application contracts, and callback execution. No hard-realtime guarantees, audio synthesis, DSP, discovery, delivery acknowledgement, clock drift model, or automatic competition registration. The core profile permanently excludes OSC 1.1 recursive //, Unicode protocol fields, recursive brace-pattern extensions, legacy typetag guessing and implicit numeric coercion. Malformed packets are rejected, not repaired. See the conformance map for exact limits and host obligations.

    #License

    Original implementation under Apache-2.0, relying on MoonBit core only. Bounded ecosystem research and rejected alternatives are documented in duplicate-check; it is not a claim of uniqueness.

    OscError

    source
    pub suberror OscError {
      Invalid(String, Int)
      Limit(String)
    } derive(Eq, 
    Debug    )

    OscError::equal

    source
    fn OscError::equal(OscError, OscError) -> Bool

    OscError::not_equal

    source
    fn OscError::not_equal(x : OscError, y : OscError) -> Bool

    OscError::to_repr

    source

    Argument

    source
    pub(all) enum Argument {
      I32(Int)
      F32(UInt)
      Text(String)
      Blob(Bytes)
      I64(Int64)
      F64(UInt64)
      Time(TimeTag)
      Symbol(String)
      Character(Int)
      Rgba(UInt)
      Midi(UInt)
      True
      False
      Nil
      Impulse
      Array(Array[Argument])
    } derive(Eq, 
    Debug    )

    Argument::equal

    source
    fn Argument::equal(Argument, Argument) -> Bool

    Argument::not_equal

    source
    fn Argument::not_equal(x : Argument, y : Argument) -> Bool

    Argument::to_repr

    source

    DispatchPlan

    source
    pub(all) struct DispatchPlan {
      accepted : Array[Route]
      rejected : Array[Rejection]
    } derive(Eq, 
    Debug    )

    DispatchPlan::equal

    source

    DispatchPlan::not_equal

    source
    fn DispatchPlan::not_equal(x : DispatchPlan, y : DispatchPlan) -> Bool

    DispatchPlan::to_repr

    source

    Dispatcher

    source
    pub struct Dispatcher {
      // private fields
    }

    Dispatcher::add

    source
    fn Dispatcher::add(self : Dispatcher, id : Int, address : String, signature? : String?) -> Unit raise OscError

    Dispatcher::new

    source
    fn Dispatcher::new(capacity? : Int) -> Dispatcher raise OscError

    Dispatcher::plan

    source
    fn Dispatcher::plan(self : Dispatcher, message : Message, all_or_nothing? : Bool, work_limit? : Int, limits? : Limits) -> DispatchPlan raise OscError

    Limits

    source
    pub(all) struct Limits {
      packet_bytes : Int
      string_bytes : Int
      blob_bytes : Int
      arguments : Int
      elements : Int
      depth : Int
    } derive(Eq, 
    Debug    )

    Limits::default

    source
    fn Limits::default() -> Limits

    Limits::equal

    source
    fn Limits::equal(Limits, Limits) -> Bool

    Limits::not_equal

    source
    fn Limits::not_equal(x : Limits, y : Limits) -> Bool

    Limits::to_repr

    source

    Message

    source
    pub(all) struct Message {
      address : String
      arguments : Array[Argument]
    } derive(Eq, 
    Debug    )

    Message::equal

    source
    fn Message::equal(Message, Message) -> Bool

    Message::not_equal

    source
    fn Message::not_equal(x : Message, y : Message) -> Bool

    Message::to_repr

    source

    Message::type_tags

    source
    fn Message::type_tags(self : Message, limits? : Limits) -> String raise OscError

    Osc10Batch

    source
    pub(all) struct Osc10Batch {
      due : TimeTag
      messages : Array[Message]
    } derive(Eq, 
    Debug    )

    Osc10Batch::equal

    source
    fn Osc10Batch::equal(Osc10Batch, Osc10Batch) -> Bool

    Osc10Batch::not_equal

    source
    fn Osc10Batch::not_equal(x : Osc10Batch, y : Osc10Batch) -> Bool

    Osc10Batch::to_repr

    source

    Osc10Scheduler

    source
    pub struct Osc10Scheduler {
      // private fields
    }

    Osc10Scheduler::cancel

    source
    fn Osc10Scheduler::cancel(self : Osc10Scheduler, ticket : UInt64) -> Bool

    Osc10Scheduler::clear

    source
    fn Osc10Scheduler::clear(self : Osc10Scheduler) -> Int

    Osc10Scheduler::enqueue

    source
    fn Osc10Scheduler::enqueue(self : Osc10Scheduler, packet : Packet, now : TimeTag, limits? : Limits) -> Array[UInt64] raise OscError

    Transactional admission; capacity counts indivisible batches, not messages.

    Osc10Scheduler::len

    source
    fn Osc10Scheduler::len(self : Osc10Scheduler) -> Int

    Osc10Scheduler::new

    source
    fn Osc10Scheduler::new(capacity? : Int) -> Osc10Scheduler raise OscError

    Osc10Scheduler::next_due

    source
    fn Osc10Scheduler::next_due(self : Osc10Scheduler) -> TimeTag?

    Osc10Scheduler::poll

    source
    fn Osc10Scheduler::poll(self : Osc10Scheduler, now : TimeTag, max_batches? : Int) -> Array[ScheduledOsc10Batch] raise OscError

    max_batches never splits a batch, even when it contains many messages.

    Packet

    source
    pub(all) enum Packet {
      Message(Message)
      Bundle(TimeTag, Array[Packet])
    } derive(Eq, 
    Debug    )

    Packet::equal

    source
    fn Packet::equal(Packet, Packet) -> Bool

    Packet::not_equal

    source
    fn Packet::not_equal(x : Packet, y : Packet) -> Bool

    Packet::to_repr

    source

    PacketSummary

    source
    pub(all) struct PacketSummary {
      wire_bytes : Int
      messages : Int
      bundles : Int
      arguments : Int
      array_arguments : Int
      blob_bytes : Int
      max_depth : Int
    } derive(Eq, 
    Debug    )

    PacketSummary::equal

    source

    PacketSummary::not_equal

    source
    fn PacketSummary::not_equal(x : PacketSummary, y : PacketSummary) -> Bool

    PacketSummary::to_repr

    source

    Pattern

    source
    pub struct Pattern {
      // private fields
    }

    Pattern::matches

    source
    fn Pattern::matches(self : Pattern, path : String, work_limit? : Int) -> Bool raise OscError

    Pattern::source

    source
    fn Pattern::source(self : Pattern) -> String

    Rejection

    source
    pub(all) struct Rejection {
      route : Route
      expected : String
      actual : String
    } derive(Eq, 
    Debug    )

    Rejection::equal

    source
    fn Rejection::equal(Rejection, Rejection) -> Bool

    Rejection::not_equal

    source
    fn Rejection::not_equal(x : Rejection, y : Rejection) -> Bool

    Rejection::to_repr

    source

    Route

    source
    pub(all) struct Route {
      id : Int
      address : String
    } derive(Eq, 
    Debug    )

    Route::equal

    source
    fn Route::equal(Route, Route) -> Bool

    Route::not_equal

    source
    fn Route::not_equal(x : Route, y : Route) -> Bool

    Route::to_repr

    source

    Router

    source
    pub struct Router {
      // private fields
    }

    Router::add

    source
    fn Router::add(self : Router, id : Int, address : String) -> Unit raise OscError

    Router::len

    source
    fn Router::len(self : Router) -> Int

    Router::new

    source
    fn Router::new(capacity? : Int) -> Router raise OscError

    Router::remove

    source
    fn Router::remove(self : Router, id : Int) -> Bool

    Router::resolve

    source
    fn Router::resolve(self : Router, address : String, work_limit? : Int) -> Array[Route] raise OscError

    The message supplies the pattern; registered destinations are literal paths.

    Router::snapshot

    source
    fn Router::snapshot(self : Router) -> Array[Route]

    Scheduled

    source
    pub(all) struct Scheduled {
      ticket : UInt64
      due : TimeTag
      message : Message
    } derive(Eq, 
    Debug    )

    Scheduled::equal

    source
    fn Scheduled::equal(Scheduled, Scheduled) -> Bool

    Scheduled::not_equal

    source
    fn Scheduled::not_equal(x : Scheduled, y : Scheduled) -> Bool

    Scheduled::to_repr

    source

    ScheduledOsc10Batch

    source
    pub(all) struct ScheduledOsc10Batch {
      ticket : UInt64
      due : TimeTag
      messages : Array[Message]
    } derive(Eq, 
    Debug    )

    ScheduledOsc10Batch::equal

    source

    ScheduledOsc10Batch::not_equal

    source

    ScheduledOsc10Batch::to_repr

    source

    Scheduler

    source
    pub struct Scheduler {
      // private fields
    }

    Scheduler::cancel

    source
    fn Scheduler::cancel(self : Scheduler, ticket : UInt64) -> Bool

    Cancel one ticket. Removing a non-root node restores the heap in both directions.

    Scheduler::clear

    source
    fn Scheduler::clear(self : Scheduler) -> Int

    Clear pending messages without recycling ticket identities.

    Scheduler::discard_before

    source
    fn Scheduler::discard_before(self : Scheduler, cutoff : TimeTag) -> Array[Scheduled] raise OscError

    Explicit late-event policy: discard events strictly before cutoff, returning them in stable order. Equality is retained. Validation happens before any mutation.

    Scheduler::enqueue

    source
    fn Scheduler::enqueue(self : Scheduler, packet : Packet, now : TimeTag, limits? : Limits) -> Array[UInt64] raise OscError

    Admission is transactional: flatten and all capacities checked before mutation.

    Scheduler::len

    source
    fn Scheduler::len(self : Scheduler) -> Int

    Scheduler::new

    source
    fn Scheduler::new(capacity? : Int) -> Scheduler raise OscError

    Scheduler::next_due

    source
    fn Scheduler::next_due(self : Scheduler) -> TimeTag?

    Scheduler::poll

    source
    fn Scheduler::poll(self : Scheduler, now : TimeTag, max_count? : Int) -> Array[Scheduled] raise OscError

    SizeFramer

    source
    pub struct SizeFramer {
      // private fields
    }

    Size-prefix framing only: returned frames still require decode().

    SizeFramer::buffered

    source
    fn SizeFramer::buffered(self : SizeFramer) -> Int

    SizeFramer::feed

    source
    fn SizeFramer::feed(self : SizeFramer, chunk : Bytes) -> Array[Bytes] raise OscError

    Entire feed is transactional, including completed frames before a bad header. On failure no input is accepted: retry corrected bytes or explicitly reset().

    SizeFramer::finish

    source
    fn SizeFramer::finish(self : SizeFramer) -> Unit raise OscError

    SizeFramer::new

    source
    fn SizeFramer::new(max_frame? : Int, max_feed? : Int, max_frames? : Int) -> SizeFramer raise OscError

    SizeFramer::reset

    source
    fn SizeFramer::reset(self : SizeFramer) -> Unit

    SlipFramer

    source
    pub struct SlipFramer {
      // private fields
    }

    RFC 1055 SLIP byte-stuffing, constrained to nonempty aligned OSC frames.

    SlipFramer::buffered

    source
    fn SlipFramer::buffered(self : SlipFramer) -> Int

    SlipFramer::feed

    source
    fn SlipFramer::feed(self : SlipFramer, chunk : Bytes) -> Array[Bytes] raise OscError

    Empty ENDs are synchronization markers. Invalid escapes roll back the whole feed.

    SlipFramer::finish

    source
    fn SlipFramer::finish(self : SlipFramer) -> Unit raise OscError

    SlipFramer::new

    source
    fn SlipFramer::new(max_frame? : Int, max_feed? : Int, max_frames? : Int) -> SlipFramer raise OscError

    SlipFramer::reset

    source
    fn SlipFramer::reset(self : SlipFramer) -> Unit

    TimeTag

    source
    pub(all) struct TimeTag {
      seconds : UInt
      fraction : UInt
    } derive(Eq, 
    Debug    )

    TimeTag::add_ticks

    source
    fn TimeTag::add_ticks(self : TimeTag, ticks : UInt64) -> TimeTag raise OscError

    TimeTag::bits

    source
    fn TimeTag::bits(self : TimeTag) -> UInt64

    TimeTag::distance_ticks

    source
    fn TimeTag::distance_ticks(self : TimeTag, later : TimeTag) -> UInt64 raise OscError

    TimeTag::equal

    source
    fn TimeTag::equal(TimeTag, TimeTag) -> Bool

    TimeTag::from_bits

    source
    fn TimeTag::from_bits(bits : UInt64) -> TimeTag

    TimeTag::from_unix

    source
    fn TimeTag::from_unix(seconds : Int64, nanoseconds? : Int) -> TimeTag raise OscError

    Era 0 only, floors nanoseconds to the preceding 2^-32-second tick.

    TimeTag::immediate

    source
    fn TimeTag::immediate() -> TimeTag

    TimeTag::is_immediate

    source
    fn TimeTag::is_immediate(self : TimeTag) -> Bool

    TimeTag::not_equal

    source
    fn TimeTag::not_equal(x : TimeTag, y : TimeTag) -> Bool

    TimeTag::resolve

    source
    fn TimeTag::resolve(self : TimeTag, now : TimeTag) -> TimeTag raise OscError

    TimeTag::to_repr

    source

    TimeTag::to_unix

    source
    fn TimeTag::to_unix(self : TimeTag) -> (Int64, Int) raise OscError

    TimedMessage

    source
    pub(all) struct TimedMessage {
      due : TimeTag
      message : Message
      order : Int
    } derive(Eq, 
    Debug    )

    TimedMessage::equal

    source

    TimedMessage::not_equal

    source
    fn TimedMessage::not_equal(x : TimedMessage, y : TimedMessage) -> Bool

    TimedMessage::to_repr

    source

    compile_pattern

    source
    fn compile_pattern(text : String) -> Pattern raise OscError

    decode

    source
    fn decode(bytes : Bytes, limits? : Limits) -> Packet raise OscError

    decode_message

    source
    fn decode_message(bytes : Bytes, limits? : Limits) -> Message raise OscError

    decode_osc10

    source
    fn decode_osc10(bytes : Bytes, limits? : Limits) -> Packet raise OscError

    double_argument

    source
    fn double_argument(value : Double) -> Argument

    encode

    source
    fn encode(packet : Packet, limits? : Limits) -> Bytes raise OscError

    encode_message

    source
    fn encode_message(message : Message, limits? : Limits) -> Bytes raise OscError

    encode_osc10

    source
    fn encode_osc10(packet : Packet, limits? : Limits) -> Bytes raise OscError

    flatten

    source
    fn flatten(packet : Packet, now : TimeTag, limits? : Limits) -> Array[TimedMessage] raise OscError

    Returns owned message trees in depth-first wire order, not sorted due order.

    float_argument

    source
    fn float_argument(value : Float) -> Argument

    from_json

    source
    fn from_json(value : Json, limits? : Limits) -> Packet raise OscError

    hex_decode

    source
    fn hex_decode(text : String, max_bytes? : Int) -> Bytes raise OscError

    hex_encode

    source
    fn hex_encode(bytes : Bytes, max_bytes? : Int) -> String raise OscError

    matches

    source
    fn matches(pattern : String, path : String, work_limit? : Int) -> Bool raise OscError

    parse_json

    source
    fn parse_json(text : String, limits? : Limits) -> Packet raise OscError

    Text parsing has both a byte/code-unit cap and parser nesting cap.

    plan_osc10

    source
    fn plan_osc10(packet : Packet, now : TimeTag, limits? : Limits) -> Array[Osc10Batch] raise OscError

    Owns data and preserves each bundle's direct-message atomic group. Hosts must run an entire returned group without unrelated callback processing.

    size_frame

    source
    fn size_frame(bytes : Bytes, max_frame? : Int) -> Bytes raise OscError

    slip_frame

    source
    fn slip_frame(bytes : Bytes, max_frame? : Int) -> Bytes raise OscError

    Adds leading and trailing END for synchronization; worst case 2*n+2 bytes.

    summarize

    source
    fn summarize(packet : Packet, limits? : Limits) -> PacketSummary raise OscError

    First validates all budgets; never inspect untrusted models recursively first.

    to_json

    source
    fn to_json(packet : Packet, limits? : Limits) -> Json raise OscError

    Versioned tagged-array schema. Integers and IEEE/NTP bits are fixed-width hex, never JSON numbers: NaN payloads, signed zero and all 64-bit values survive.

    validate_address

    source
    fn validate_address(address : String) -> Unit raise OscError

    validate_method

    source
    fn validate_method(address : String) -> Unit raise OscError

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io