spec: ocp-1.md — payload tables, absolute-ms seek, one time convention

[JarbasAl]

Refines OVOS-OCP-1 with internally consistent payload contracts.

Changes

• §4.2.1 ovos.common_play.play payload — media (media entry, required), playlist (defaults to [media]), disambiguation (defaults to the playlist), repeat.
• §4.2.2 absolute seek — position is an absolute millisecond offset; relative "skip forward N" is resolved by the requester from the §4.4 state reports. One addressing mode keeps concurrent seekers from compounding each other's offsets.
• §4.2 — search.start / search.end are first-class bracketing Messages with MUST emission points.
• §3.1 / §4.4 — every axis member has a stable numeric code and the code is what travels on the wire; PlayerState codes assigned (0/1/2); shared state-report payload shape; track-state axis described (disambiguation / queued / playing, qualified by backend kind; playing implies PlayerState.PLAYING, pausing never a track-state value).
• §4.5 media entry — the track object exchanged by requests and state consumers; consumers MUST ignore unknown fields. length is milliseconds with -1 = unknown/live, aligning the whole media surface (seek, media entry, GUI-1 player templates) on one time convention.
• Version 1 → 2: absolute-ms seek and ms durations are incompatible with pre-spec conventions (VERSIONING.md).
• CHANGELOG entry appended under a new class-2 section.

Follow-ups

• Numeric codes for the remaining axes (MediaState, track state, PlaybackType, media_type) still need a normative registry; only PlayerState is coded here.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5fe5b80f-aeca-45a2-808b-29992a95f44d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spec/ocp-1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}