feat(songLyrics): add cue byte offsets

[ranokay]

Summary

This follow-up amends the songLyrics v2 cue model to disambiguate repeated timed/untimed text within a cueLine.value.

It adds optional byteStart / byteEnd fields on cue, defined as 0-based inclusive UTF-8 byte offsets into the final parent cueLine.value, with no normalization step.

Changes

• add byteStart / byteEnd to the cue docs and OpenAPI schema
• document them as an all-or-none pair
• document that they are only valid relative to cueLine.value
• document the invariant byteStart <= byteEnd
• propagate the contract text through cueLine, structuredLyrics, songLyrics, and getLyricsBySongId

[netlify]

✅ Deploy Preview for opensubsonic ready!

Name	Link
🔨 Latest commit	a6abe99
🔍 Latest deploy log	https://app.netlify.com/projects/opensubsonic/deploys/69cf84c8892daa0008fef6fd
😎 Deploy Preview	https://deploy-preview-228--opensubsonic.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

This PR updates the songLyrics v2 (enhanced) cue model documentation and OpenAPI schemas to support optional byteStart / byteEnd UTF-8 byte offsets on cues, allowing clients to disambiguate repeated timed/untimed text within a cueLine.value.

Changes:

• Add byteStart / byteEnd fields to the cue OpenAPI schema and document their contract (all-or-none, relative to cueLine.value, inclusive, UTF-8, no normalization, byteStart <= byteEnd).
• Propagate the new offset semantics through related OpenAPI descriptions (structuredLyrics, cueLine, getLyricsBySongId).
• Add/extend docs and examples showing how offsets disambiguate repeated tokens.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
openapi/schemas/StructuredLyrics.json	Notes that cues may include byte offsets into cueLine.value in enhanced synced responses.
openapi/schemas/CueLine.json	Documents cueLine.value requirement when any nested cue uses byte offsets and references offsets in cue.
openapi/schemas/Cue.json	Adds byteStart / byteEnd properties with minimum bounds and detailed contract descriptions.
openapi/endpoints/getLyricsBySongId.json	Updates enhanced parameter descriptions to mention optional cue byte offsets.
content/en/docs/Responses/structuredLyrics.md	Documents offsets at the structuredLyrics v2 level and clarifies offset scope.
content/en/docs/Responses/cueLine.md	Adds an example showing ambiguous repeated text disambiguation and updates field details.
content/en/docs/Responses/cue.md	Adds an example and contract note for byteStart / byteEnd.
content/en/docs/Extensions/songLyrics.md	Updates extension feature list and defines offset semantics.
content/en/docs/Endpoints/getLyricsBySongId.md	Updates parameter docs, adds an ambiguous-text example, and documents offset invariants in implementation notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Tolriq]

Do we want that optional ?

[ranokay]

Maybe keep them optional in the schema, but conditionally required by the spec?

If cue order + cue.value is enough to map cues back to cueLine.value unambiguously, offsets can be omitted. If not, then byteStart / byteEnd must be present for the relevant cues.

That fixes the repeated timed/untimed token case without forcing every server to emit byte offsets for all cues.

[Tolriq]

The thing is that if the server needs to be able to handle this case it means it can emit those. Making that optional means that servers must find if there's duplicates or not and if emitting or not, and clients needs to handle both the case with or without those.

This only brings complexity on both ends for no gain, it's actually better to enforce it so every one handle only one case.

[ranokay]

Gotcha. If we do that, cueLine.value should probably also become required whenever cueLine.cue is present, since the byte offsets are defined relative to that exact string. Otherwise the offsets are mandatory but their reference text is still optional.

[Tolriq]

It's already required in your spec no ?

[ranokay]

No, not currently. It’s only conditionally required when byte offsets are emitted.

[Tolriq]

I looked at the wrong value. Yes value should be required

[ranokay]

@epoupon @kgarner7 could you take a look?