<!-- source-hash: 91af97ee03e3f4fa98e259bed1e212df -->
Builds the captions API URL for a video entity, returning the HTTPS path to the `/api/captions/[entityType]/[entityId]` endpoint that serves VTT content for iOS native fullscreen subtitles.

## Key Components

### `getCaptionsUrl(entityType, entityId, srtContent?)`

| Parameter | Type | Description |
|---|---|---|
| `entityType` | `string` | Entity-type discriminator for the reverse-proxied captions route |
| `entityId` | `string \| number` | Unique identifier of the video entity |
| `srtContent` | `string \| null \| undefined` | Raw SRT subtitle content; returns `undefined` if absent |

**Returns:** `string | undefined` — A cache-busted URL of the form `/api/captions/{entityType}/{entityId}?v={hash}`, or `undefined` when no SRT content exists.

**Cache-busting strategy:** The `?v=` hash is derived from the SRT content length combined with the first 8 non-whitespace characters. This forces iOS Safari to re-fetch the VTT track when subtitles are regenerated, working around Safari's aggressive `<track>` `src` caching.

## Usage Example

```typescript
import { getCaptionsUrl } from './captions-url'

// Returns a cache-busted captions URL
const url = getCaptionsUrl('ticket', 42, 'WEBVTT\n\n1\n00:00:01...')
// → '/api/captions/ticket/42?v=23-WEBVTT'

// Returns undefined when no subtitles exist
const noUrl = getCaptionsUrl('ticket', 42, null)
// → undefined

// Use in a <track> element
const trackSrc = getCaptionsUrl(entityType, entityId, video.srt_content)
if (trackSrc) {
  // <track kind="subtitles" src={trackSrc} default />
}
```

## Notes

- Ported from the Flamingo hub's `lib/utils/captions-url.ts`; the hub's `VideoEnabledEntityType` enum is widened to `string` so embedders can pass any entity-type their proxied route expects.
- VTT conversion from SRT happens server-side at the `/api/captions/...` endpoint, not in this utility.

**Source:** [`lib/captions-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/lib/captions-url.ts)