Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt

Use this file to discover all available pages before exploring further.

The SDK has one billable event type: stream acquisition. Browsing, searching, library reads, and metadata fetches do not bill. The two RPCs that matter are:
  • StreamingService.AcquireMusicStream(song_id, max_quality) — billed as a music stream.
  • StreamingService.AcquireVideoStream(movie_id | episode_id, max_quality) — billed as a video stream. The request carries a oneof content { MovieID movie_id; EpisodeID episode_id }.
Both require an OAuth access token with the stream scope. API keys cannot acquire streams.

​
What you get back

Each acquire returns a StreamInfo payload with:
  • manifest_url — the time-limited stream URL (HLS m3u8 or DASH mpd).
  • expires_in_seconds — seconds remaining until the URL expires (relative, not an absolute timestamp).
  • drm_scheme, license_url, drm_params — DRM metadata when the stream is protected. drm_scheme is DRM_SCHEME_UNSPECIFIED for clear streams. drm_params is a string→string map of scheme-specific values (e.g. certificate_url for FairPlay).
  • available_qualities — the quality tiers the server actually exposes for this stream (each entry is a QualityOption { label, bitrate_kbps, codec }). The server may pick a tier below the requested max_quality if the user is not entitled to it.
The URL is valid for expires_in_seconds. Re-acquire to get a fresh URL. Re-acquiring within the lifetime of an existing URL does not re-bill — it returns a fresh signed URL for the same logical stream.

​
What counts as a billable event

EventBillable?
First AcquireMusicStream for (user, song) in a sessionYes
Re-acquiring the same (user, song) while the prior URL is still validNo (same logical stream)
Re-acquiring after URL expiryYes (new logical stream)
Acquiring for a different songYes
Acquiring at a different quality for the same songYes
GetSong, Search, BrowseCharts, …Never
The same rules apply to video.

​
No playback reporting

There is no ReportPlaybackStart / ReportPlaybackEnd / ReportPlaybackProgress RPC, by design. The billable event is the acquire, not the play. This keeps the SDK simple and the billing contract unambiguous: if your client acquires a stream, that’s the event, regardless of whether the user actually pressed play.

​
Concurrency

Stream acquisition has its own concurrency cap separate from request-rate limits — the cap is per OAuth user, not per API key. Exceeding it returns ERROR_CODE_PERMISSION_DENIED with a message indicating concurrent stream limits. This is enforced at the entitlement layer, not the rate-limit layer.

​
DRM

When drm_scheme is anything other than DRM_SCHEME_UNSPECIFIED, the client must:
  1. Read drm_scheme — one of DRM_SCHEME_FAIRPLAY (Apple FairPlay), DRM_SCHEME_WIDEVINE (Google Widevine), DRM_SCHEME_PLAYREADY (Microsoft PlayReady), or DRM_SCHEME_CLEARKEY (W3C Clear Key, test scenarios only).
  2. POST a license request to license_url with the platform-specific key request body. license_url is empty for CLEARKEY and unprotected streams.
  3. Pass any scheme-specific values from drm_params (e.g. certificate_url for FairPlay) into the platform DRM module before playback.
Generated TypeScript and Swift clients expose typed wrappers; raw HTTP callers should forward drm_scheme, license_url, and drm_params opaquely to the platform layer.

​
Best practices

  • Acquire just-in-time. Don’t pre-acquire entire playlists; you’ll bill for streams the user never plays.
  • Refresh on expiry, not eagerly. Honor expires_in_seconds and only re-acquire when the URL is about to expire or has expired.
  • Surface acquire failures cleanly. A failed acquire is the right time to show DRM errors, region-restriction errors, or entitlement errors to the user.
  • Use max_quality deliberately. Acquiring AUDIO_QUALITY_HIGH for a user only entitled to AUDIO_QUALITY_STANDARD is downgraded server-side — no separate negotiation step needed. Audio tiers: AUDIO_QUALITY_LOW, AUDIO_QUALITY_STANDARD, AUDIO_QUALITY_HIGH, AUDIO_QUALITY_LOSSLESS. Video tiers: VIDEO_QUALITY_SD, VIDEO_QUALITY_HD, VIDEO_QUALITY_FULL_HD, VIDEO_QUALITY_UHD.