@pulsefield/protocol 0.0.1 → 0.0.3

package/gen/swift/pulsefield/protocol/v1/mapper.pb.swift

@@ -0,0 +1,143 @@
+// DO NOT EDIT.
+// swift-format-ignore-file
+// swiftlint:disable all
+//
+// Generated by the Swift generator plugin for the protocol buffer compiler.
+// Source: pulsefield/protocol/v1/mapper.proto
+//
+// For information on using the generated types, please see the documentation:
+//   https://github.com/apple/swift-protobuf/
+
+import SwiftProtobuf
+
+// If the compiler emits an error on this type, it is because this file
+// was generated by a version of the `protoc` Swift plug-in that is
+// incompatible with the version of SwiftProtobuf to which you are linking.
+// Please ensure that you are building against the same version of the API
+// that was used to generate this file.
+fileprivate nonisolated struct _GeneratedWithProtocGenSwiftVersion: SwiftProtobuf.ProtobufAPIVersionCheck {
+  struct _2: SwiftProtobuf.ProtobufAPIVersion_2 {}
+  typealias Version = _2
+}
+
+public nonisolated struct Pulsefield_Protocol_V1_MapperStreamBeginEvent: Sendable {
+  // SwiftProtobuf.Message conformance is added in an extension below. See the
+  // `Message` and `Message+*Additions` files in the SwiftProtobuf library for
+  // methods supported on all messages.
+
+  public var tokenContractVersion: UInt32 = 0
+
+  public var audioLengthMs: UInt32 {
+    get {_audioLengthMs ?? 0}
+    set {_audioLengthMs = newValue}
+  }
+  /// Returns true if `audioLengthMs` has been explicitly set.
+  public var hasAudioLengthMs: Bool {self._audioLengthMs != nil}
+  /// Clears the value of `audioLengthMs`. Subsequent reads from it will return its default value.
+  public mutating func clearAudioLengthMs() {self._audioLengthMs = nil}
+
+  public var unknownFields = SwiftProtobuf.UnknownStorage()
+
+  public init() {}
+
+  fileprivate var _audioLengthMs: UInt32? = nil
+}
+
+public nonisolated struct Pulsefield_Protocol_V1_HitObjectTokenEvent: Sendable {
+  // SwiftProtobuf.Message conformance is added in an extension below. See the
+  // `Message` and `Message+*Additions` files in the SwiftProtobuf library for
+  // methods supported on all messages.
+
+  public var tokenID: UInt32 = 0
+
+  public var msInRefAudio: UInt32 = 0
+
+  public var tokenIndex: UInt32 = 0
+
+  public var unknownFields = SwiftProtobuf.UnknownStorage()
+
+  public init() {}
+}
+
+// MARK: - Code below here is support for the SwiftProtobuf runtime.
+
+fileprivate nonisolated let _protobuf_package = "pulsefield.protocol.v1"
+
+nonisolated extension Pulsefield_Protocol_V1_MapperStreamBeginEvent: SwiftProtobuf.Message, SwiftProtobuf._MessageImplementationBase, SwiftProtobuf._ProtoNameProviding {
+  public static let protoMessageName: String = _protobuf_package + ".MapperStreamBeginEvent"
+  public static let _protobuf_nameMap = SwiftProtobuf._NameMap(bytecode: "\0\u{4}\u{2}token_contract_version\0\u{3}audio_length_ms\0\u{b}route\0\u{c}\u{1}\u{1}")
+
+  public mutating func decodeMessage<D: SwiftProtobuf.Decoder>(decoder: inout D) throws {
+    while let fieldNumber = try decoder.nextFieldNumber() {
+      // The use of inline closures is to circumvent an issue where the compiler
+      // allocates stack space for every case branch when no optimizations are
+      // enabled. https://github.com/apple/swift-protobuf/issues/1034
+      switch fieldNumber {
+      case 2: try { try decoder.decodeSingularUInt32Field(value: &self.tokenContractVersion) }()
+      case 3: try { try decoder.decodeSingularUInt32Field(value: &self._audioLengthMs) }()
+      default: break
+      }
+    }
+  }
+
+  public func traverse<V: SwiftProtobuf.Visitor>(visitor: inout V) throws {
+    // The use of inline closures is to circumvent an issue where the compiler
+    // allocates stack space for every if/case branch local when no optimizations
+    // are enabled. https://github.com/apple/swift-protobuf/issues/1034 and
+    // https://github.com/apple/swift-protobuf/issues/1182
+    if self.tokenContractVersion != 0 {
+      try visitor.visitSingularUInt32Field(value: self.tokenContractVersion, fieldNumber: 2)
+    }
+    try { if let v = self._audioLengthMs {
+      try visitor.visitSingularUInt32Field(value: v, fieldNumber: 3)
+    } }()
+    try unknownFields.traverse(visitor: &visitor)
+  }
+
+  public static func ==(lhs: Pulsefield_Protocol_V1_MapperStreamBeginEvent, rhs: Pulsefield_Protocol_V1_MapperStreamBeginEvent) -> Bool {
+    if lhs.tokenContractVersion != rhs.tokenContractVersion {return false}
+    if lhs._audioLengthMs != rhs._audioLengthMs {return false}
+    if lhs.unknownFields != rhs.unknownFields {return false}
+    return true
+  }
+}
+
+nonisolated extension Pulsefield_Protocol_V1_HitObjectTokenEvent: SwiftProtobuf.Message, SwiftProtobuf._MessageImplementationBase, SwiftProtobuf._ProtoNameProviding {
+  public static let protoMessageName: String = _protobuf_package + ".HitObjectTokenEvent"
+  public static let _protobuf_nameMap = SwiftProtobuf._NameMap(bytecode: "\0\u{3}token_id\0\u{3}ms_in_ref_audio\0\u{3}token_index\0")
+
+  public mutating func decodeMessage<D: SwiftProtobuf.Decoder>(decoder: inout D) throws {
+    while let fieldNumber = try decoder.nextFieldNumber() {
+      // The use of inline closures is to circumvent an issue where the compiler
+      // allocates stack space for every case branch when no optimizations are
+      // enabled. https://github.com/apple/swift-protobuf/issues/1034
+      switch fieldNumber {
+      case 1: try { try decoder.decodeSingularUInt32Field(value: &self.tokenID) }()
+      case 2: try { try decoder.decodeSingularUInt32Field(value: &self.msInRefAudio) }()
+      case 3: try { try decoder.decodeSingularUInt32Field(value: &self.tokenIndex) }()
+      default: break
+      }
+    }
+  }
+
+  public func traverse<V: SwiftProtobuf.Visitor>(visitor: inout V) throws {
+    if self.tokenID != 0 {
+      try visitor.visitSingularUInt32Field(value: self.tokenID, fieldNumber: 1)
+    }
+    if self.msInRefAudio != 0 {
+      try visitor.visitSingularUInt32Field(value: self.msInRefAudio, fieldNumber: 2)
+    }
+    if self.tokenIndex != 0 {
+      try visitor.visitSingularUInt32Field(value: self.tokenIndex, fieldNumber: 3)
+    }
+    try unknownFields.traverse(visitor: &visitor)
+  }
+
+  public static func ==(lhs: Pulsefield_Protocol_V1_HitObjectTokenEvent, rhs: Pulsefield_Protocol_V1_HitObjectTokenEvent) -> Bool {
+    if lhs.tokenID != rhs.tokenID {return false}
+    if lhs.msInRefAudio != rhs.msInRefAudio {return false}
+    if lhs.tokenIndex != rhs.tokenIndex {return false}
+    if lhs.unknownFields != rhs.unknownFields {return false}
+    return true
+  }
+}

package/package.json

@@ -1,13 +1,65 @@
 {
   "name": "@pulsefield/protocol",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.0.3",
+  "description": "Shared Protocol Buffers contracts for Pulsefield clients and model services.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pulsefield/protocol.git"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "packageManager": "npm@11.12.1",
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=11.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    "./proto/*": "./proto/*",
+    "./gen/swift/*": "./gen/swift/*",
+    "./gen/python/*": "./gen/python/*",
+    "./docs/*": "./docs/*",
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "tools": "node --version && npm --version && buf --version && prettier --version",
+    "generate": "npm run proto:generate",
+    "proto:format": "buf format -w proto",
+    "proto:lint": "buf lint",
+    "proto:generate": "buf generate && node tools/ensure-python-typed.mjs",
+    "generated:check": "node tools/check-generated.mjs",
+    "check": "buf lint && npm run generated:check",
+    "bootstrap:check": "npm run check && npm run python:check && npm run swift:build",
+    "python:check": "node tools/check-python-package.mjs",
+    "python:build": "python3 -m build --sdist --wheel --outdir dist/",
+    "swift:build": "swift build",
+    "format": "prettier --check .",
+    "format:write": "prettier --write ."
   },
-  "keywords": [],
+  "keywords": [
+    "pulsefield",
+    "protobuf",
+    "protocol"
+  ],
   "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "files": [
+    "proto",
+    "gen",
+    "docs",
+    "tools",
+    "buf.yaml",
+    "buf.gen.yaml",
+    "Package.swift",
+    "pyproject.toml",
+    "README.md",
+    "PROTOCOL_GUIDELINES.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@bufbuild/buf": "1.70.0",
+    "prettier": "3.8.4"
+  }
 }

package/proto/pulsefield/protocol/v1/core.proto

@@ -0,0 +1,57 @@
+syntax = "proto3";
+
+package pulsefield.protocol.v1;
+
+// Capability advertised by a node before domain-specific traffic begins.
+message NodeCapability {
+  NodeCapabilityKind kind = 1;
+
+  // Stable capability identifier, such as "mapper.tuple_tokens" or "hardware.input".
+  string name = 2;
+
+  // Capability-specific contract or implementation version.
+  string version = 3;
+  NodeCapabilityDirection direction = 4;
+}
+
+// Initial topology announcement for apps, services, tools, and hardware bridges.
+message NodeHello {
+  // Stable node identifier within a Pulsefield graph or room.
+  string node_id = 1;
+
+  NodeRole role = 2;
+
+  repeated NodeCapability capabilities = 3;
+
+  // Protocol package version spoken by this node, such as "0.0.3".
+  string protocol_version = 4;
+
+  // Stable application or service identifier, such as "pulsefield.host".
+  string app_id = 5;
+}
+
+enum NodeRole {
+  NODE_ROLE_UNSPECIFIED = 0;
+  NODE_ROLE_HOST = 1;
+  NODE_ROLE_PLAYER_CLIENT = 2;
+  NODE_ROLE_MODEL_SERVICE = 3;
+  NODE_ROLE_HARDWARE = 4;
+  NODE_ROLE_DEBUG_TOOL = 5;
+}
+
+enum NodeCapabilityKind {
+  NODE_CAPABILITY_KIND_UNSPECIFIED = 0;
+  NODE_CAPABILITY_KIND_RECOGNITION = 1;
+  NODE_CAPABILITY_KIND_TIMING = 2;
+  NODE_CAPABILITY_KIND_MAPPER = 3;
+  NODE_CAPABILITY_KIND_PLAYER_STREAM = 4;
+  NODE_CAPABILITY_KIND_HARDWARE = 5;
+  NODE_CAPABILITY_KIND_DEBUG = 6;
+}
+
+enum NodeCapabilityDirection {
+  NODE_CAPABILITY_DIRECTION_UNSPECIFIED = 0;
+  NODE_CAPABILITY_DIRECTION_PRODUCER = 1;
+  NODE_CAPABILITY_DIRECTION_CONSUMER = 2;
+  NODE_CAPABILITY_DIRECTION_BIDIRECTIONAL = 3;
+}

package/proto/pulsefield/protocol/v1/envelope.proto

@@ -0,0 +1,49 @@
+syntax = "proto3";
+
+package pulsefield.protocol.v1;
+
+import "pulsefield/protocol/v1/core.proto";
+import "pulsefield/protocol/v1/inference.proto";
+import "pulsefield/protocol/v1/mapper.proto";
+
+// Transport-agnostic binary envelope shared by Pulsefield nodes.
+message Envelope {
+  // Inference/play session identifier. Empty for node-level or graph-level messages.
+  string session_id = 1;
+
+  // Sender-local monotonic sequence number within a session. per source_node_id + session_id
+  uint64 sequence = 2;
+
+  // Sender wall-clock timestamp in Unix milliseconds, when available.
+  int64 sent_at_unix_ms = 3;
+
+  // Node that produced this envelope, when the transport has graph identity.
+  string source_node_id = 4;
+
+  // Intended recipient node. Empty means the session or transport decides routing.
+  string target_node_id = 5;
+
+  // globally unique enough, sender-generated
+  string message_id = 6;
+
+  // Related message or request identifier for response and stream correlation.
+  string correlation_id = 7;
+
+  oneof payload {
+    // Graph identity announcement, usually sent before domain-specific traffic.
+    NodeHello node_hello = 8;
+
+    ReadyRequest ready = 10;
+    AudioRequest audio = 11;
+    ReferenceTimeRequest reference_time = 12;
+    StopSessionRequest stop_session = 13;
+
+    // One mapper token event. The legacy JSON transport calls this hitobject_tokens.
+    MapperStreamBeginEvent mapper_stream_begin = 19;
+    HitObjectTokenEvent hit_object_token = 20;
+
+    ErrorEvent error = 21;
+    StatusEvent status = 22;
+    EndOfStreamEvent end_of_stream = 23;
+  }
+}

package/proto/pulsefield/protocol/v1/inference.proto

@@ -0,0 +1,145 @@
+syntax = "proto3";
+
+package pulsefield.protocol.v1;
+
+// Sent by a client to ask the endpoint to load models and become ready.
+message ReadyRequest {}
+
+message AudioAssetRef {
+  oneof ref {
+    string local_path = 1;
+    string uri = 2;
+    string asset_id = 3;
+  }
+
+  optional uint32 audio_length_ms = 10;
+  optional string sha256_hex = 11;
+}
+
+message AudioRequest {
+  AudioAssetRef audio = 1;
+  SyncSource sync_source = 2;
+  optional double difficulty = 3;
+  InferenceRoute route = 4;
+}
+
+// Sent by a client once ambient sync has produced a reference clock lock.
+message ReferenceTimeRequest {
+  // Current playback/reference position in the selected audio, in milliseconds.
+  uint32 ref_time_ms = 1;
+
+  // Client monotonic host-clock timestamp captured when ref_time_ms was sent.
+  uint64 local_host_time_send_ms = 2;
+
+  // Duration check in milliseconds. When present, it must match AudioRequest.
+  optional uint32 audio_length_ms = 3;
+}
+
+// Sent by a client to stop and reset an active endpoint session.
+message StopSessionRequest {
+  // Machine-readable stop reason such as "client_stop" or "peer_disconnect".
+  string reason = 1;
+}
+
+// Machine-readable endpoint failure plus a human-readable message.
+message ErrorEvent {
+  // Stable string code retained for JSON compatibility with prototype clients.
+  string code = 1;
+
+  string message = 2;
+
+  // Preferred typed error code for new protobuf consumers.
+  InferenceErrorCode error_code = 3;
+
+  // Endpoint phase that failed, such as "prepare_audio" or "stream".
+  string phase = 4;
+
+  // Route active when the failure occurred, when known.
+  InferenceRoute route = 5;
+
+  // Compatibility bucket used by the current JSON endpoint, such as "inference".
+  string error_kind = 6;
+}
+
+// Endpoint lifecycle transition or current-status notification.
+message StatusEvent {
+  // Target status after this notification.
+  EndpointStatus status = 1;
+
+  string message = 2;
+
+  // Reference-audio position associated with the status, when known.
+  optional uint32 ref_time_ms = 3;
+
+  // Sender-local monotonic host-clock timestamp in milliseconds, when known.
+  optional uint64 sender_monotonic_ms = 4;
+
+  // Previous status for transition logs.
+  EndpointStatus from_status = 5;
+
+  // Machine-readable transition reason such as "audio_path" or "reference_time".
+  string reason = 6;
+
+  // Selected audio duration associated with this transition, when known.
+  optional uint32 audio_length_ms = 7;
+
+  // Host-clock deadline for automatic cleanup after audio end, when scheduled.
+  optional uint64 reset_sender_monotonic_ms = 8;
+
+  // Route active for this status transition, when relevant.
+  InferenceRoute route = 9;
+
+  // User-facing difficulty associated with mapper preparation, when relevant.
+  optional double difficulty = 10;
+}
+
+// Sent by the model service after all tokens through complete_through_ms were emitted.
+message EndOfStreamEvent {
+  // Selected audio duration in milliseconds.
+  optional uint32 audio_length_ms = 1;
+
+  // Reference-audio time through which the stream is complete.
+  uint32 complete_through_ms = 2;
+}
+
+enum SyncSource {
+  SYNC_SOURCE_UNSPECIFIED = 0;
+  SYNC_SOURCE_BACKGROUND = 1;
+  SYNC_SOURCE_SYSTEM_AUDIO = 2;
+}
+
+enum InferenceRoute {
+  INFERENCE_ROUTE_UNSPECIFIED = 0;
+  INFERENCE_ROUTE_MAPPER = 1;
+
+  // Timing-only route selected by the legacy JSON is_mock/isMock flag.
+  INFERENCE_ROUTE_TIMING_MOCK = 2;
+}
+
+enum EndpointStatus {
+  ENDPOINT_STATUS_UNSPECIFIED = 0;
+  ENDPOINT_STATUS_READY = 1;
+  ENDPOINT_STATUS_AUDIO_PREPARING = 2;
+  ENDPOINT_STATUS_AUDIO_READY = 3;
+  ENDPOINT_STATUS_STREAMING = 4;
+  ENDPOINT_STATUS_STOPPED = 5;
+  ENDPOINT_STATUS_FAILED = 6;
+
+  // Endpoint has not completed initial readiness startup.
+  ENDPOINT_STATUS_COLD = 7;
+
+  // No active session exists for the envelope session_id.
+  ENDPOINT_STATUS_NO_SESSION = 8;
+}
+
+enum InferenceErrorCode {
+  INFERENCE_ERROR_CODE_UNSPECIFIED = 0;
+  INFERENCE_ERROR_CODE_PROTOCOL_ERROR = 1;
+  INFERENCE_ERROR_CODE_INVALID_DEVICE = 2;
+  INFERENCE_ERROR_CODE_AUDIO_NOT_FOUND = 3;
+  INFERENCE_ERROR_CODE_INFERENCE_FAILED = 4;
+  INFERENCE_ERROR_CODE_SESSION_NOT_FOUND = 5;
+  INFERENCE_ERROR_CODE_SESSION_OWNERSHIP_CONFLICT = 6;
+  INFERENCE_ERROR_CODE_AUDIO_NOT_PREPARED = 7;
+  INFERENCE_ERROR_CODE_UNSUPPORTED_ROUTE = 8;
+}

package/proto/pulsefield/protocol/v1/mapper.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package pulsefield.protocol.v1;
+
+message MapperStreamBeginEvent {
+  reserved 1;
+  reserved "route";
+
+  uint32 token_contract_version = 2;
+  optional uint32 audio_length_ms = 3;
+}
+
+message HitObjectTokenEvent {
+  uint32 token_id = 1;
+  uint32 ms_in_ref_audio = 2;
+  uint32 token_index = 3;
+}

package/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pulsefield-protocol"
+version = "0.0.3"
+description = "Shared Protocol Buffers contracts for Pulsefield clients and model services."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = []
+keywords = ["pulsefield", "protobuf", "protocol"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["protobuf>=5.26.1,<6"]
+
+[project.urls]
+Homepage = "https://github.com/Pulsefield/protocol"
+Repository = "https://github.com/Pulsefield/protocol"
+
+[tool.setuptools]
+package-dir = { "" = "gen/python" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["gen/python"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"pulsefield.protocol" = ["py.typed"]
+"pulsefield.protocol.v1" = ["*.pyi"]