User Profile Specific Recording API v4
- Thomas Langenskiold
- Tung Hoang (Unlicensed)
- Garrick Lam (Unlicensed)
Introduction
Users can request recordings of programs that air on channels that provide the recording service. Users can also request that new recordings are made automatically on their behalf as they become available in the channel's broadcast schedule. Recordings are owned by individual user profiles, but all user profiles of one user account share a common recording quota and a common set of licenses to record.
The recording API v4 spec can be viewed at Recordings v4
Entities overview
| Entity | Purpose |
|---|---|
| Broadcast slot | This entity originates from EPG API v4. It identifies a time slot on a channel where a program is aired. If the time slot is in the future, it may change or be removed depending on the broadcast schedule for that particular channel. |
| Recording | Specifies recording of one broadcast slot for one user profile. It may be created explicitly by the user or automatically as part of an automated recording request. The recorded broadcast slot may be in the future or in the past, and as such it may or may not be available for streaming. |
| Recording Group | A group of Recordings. Recordings are automatically grouped by series. If a recording has no series, then they are part of the special "ungrouped" group. |
| Automated Recording Request | A request by the user to automatically create recordings for new Broadcast slots as they become available. |
Recording
Endpoints Overview
| Endpoint | HTTP method | Purpose |
|---|---|---|
/api/recordings/v4/user_profiles/{user_profile_id}/recordings | GET | Search for recordings belonging to user profile |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings | POST | Create a new recording |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/{recording_id} | PATCH | Update a recording |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/{recording_id} | DELETE | Remove a recording |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/batch_delete_recordings | POST | Remove multiple recordings in batch |
/api/recordings/v4/user_profiles/{user_profile_id}/recorded_broadcast_slots | GET | Get all recorded broadcast slots for user profile |
/api/recordings/v4/user/{user_id}/storage_quota | GET | Get user's storage quota |
/api/recordings/v4/most_popular/{period} | GET | Get most recorded broadcast slots for a given period |
A user can create a new recording for their profile by calling the create recording endpoint. A user may record a program if the following are true:
- Requested broadcast slot is recordable, i.e. it exists and is not blacklisted
- Requested channel is recordable, i.e. the channel provides the recording service
- User has sufficient license to record requested broadcast slot
- User has sufficient storage space to record requested broadcast slot
- Requested broadcast slot is within the channel-specific recording window.
When creating a recording, the client must provide the ID of the broadcast slot to be recorded, as obtained from EPG API v4.
Until the new EPG API v4 becomes available, clients can provide a programUid as obtained from EPG API v3 in place of the Broadcast slot ID. Note that this feature is temporary and will be removed in a future release.
The user can see their available storage quota using the storage quota endpoint.
The recording may be marked as favourite on creation and it can be marked or unmarked as favourite by calling the update recording endpoint.
Individual recordings can be deleted by calling the delete recording endpoint, or in a batch of multiple recordings by calling the batch delete recordings endpoint.
The purpose of the recorded broadcast slots endpoint is to show whether a recording has been added for some given recorded slots or not. This is useful for example in an EPG view.
A list of the most recorded broadcast slots can be retrieved with the most popular endpoint.
Streaming
If a recording is streamable, the available stream URLs can be obtained by calling the streams API with the ID of the Recording. A recording can be streamed once the backend has finished processing it, which may be up to 20 minutes after the program has aired. If the channel supports live buffer streaming, the recording can be streamed even as soon as it has begun airing. The only way to know if a recording is streamable is to call the streams API. We advise that clients do not call the streams API from a "list" view. Instead, clients should only call the streams API when the user selects a specific recording. This is in order to not overload the streams API.
Any recording for a program that has not begun airing yet can not be streamable.
Recording search
Recordings can be searched using the search recordings endpoint. If no search string is provided, then all recordings for the profile are returned. Note that the response is paginated. The recording search endpoint accepts a number of filters to limit the objects returned. The series.id filter accepts a special value "null" which matches only recordings for programs with no series (e.g. movies).
Recording groups
For an improved user experience, a grouping API is provided to allow clients to display groups of recordings to the user without having to fetch all recording data at once.
Endpoints overview
| Endpoint | HTTP method | Purpose |
|---|---|---|
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/recording_groups | GET | See all recording groups |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/recording_groups/{recording_group_id}/recordings | GET | (Deprecated) See all recordings in a group |
/api/recordings/v4/user_profiles/{user_profile_id}/recordings/recording_groups/ungrouped/recordings | GET | (Deprecated) See all recordings not in any group |
The client can obtain a list of recording groups available to their profile by calling the recording groups endpoint. Recordings are grouped by series by default, but the grouping can be defined with the group_by parameter. The group_by parameter accepts series_id, channel_id or both combined. When both series_id and channel_id are combined, the endpoint will return one group per unique series_id-channel_id combination. Filters are available for favourite, starts_before, starts_after, ends_before, ends_after. The filters does not filter the groups themselves, but the recordings contained in the groups, i.e. the groups are returned as if the filtered recordings do not exist. Recordings that do not fit into any group are not included in the response.
The contents of each group can be obtained from the search recordings endpoint using appropriate filters.
Automated recording
"Automated recording" feature replaces the feature previously known as "Continuous recording".
Endpoints overview
| Endpoint | HTTP method | Purpose |
|---|---|---|
/api/recordings/v4/user_profiles/{user_profile_id}/auto_recording_requests | GET | View current auto-recording requests |
/api/recordings/v4/user_profiles/{user_profile_id}/auto_recording_requests | POST | Create new auto-recording request |
/api/recordings/v4/user_profiles/{user_profile_id}/auto_recording_requests/{recording_request_id} | PATCH | Update auto-recording request |
/api/recordings/v4/user_profiles/{user_profile_id}/auto_recording_requests/{recording_request_id} | DELETE | Delete auto-recording request |
If the user wishes to have recordings created automatically for them as they become available, they can do so using the automated recording feature. To do so, they must first create an Automated recording request by calling the create auto recording request endpoint. Users can obtain a list of their current auto recording requests by calling the get auto recording requests endpoint. Users can update those requests by calling the update recording request endpoint, and delete them using the delete auto recording request endpoint.
Creating an auto-recording request requires that the user specifies which channel they would like to record on. Auto-recording across multiple channels is supported by POST/PATCH with a null channel relationship.
If the Auto recording request has auto_delete set, the system will limit the maximum number of recordings retained based on a configurable value. The oldest of the recordings created as a result of the auto recording request will be automatically deleted as new recordings are added.
The system will not add a recording for the same program more than once, even if reruns are aired. However, if the user deletes a recording that has not yet aired, it may be automatically added again.
Automated recordings are only rules for the system to automatically keep adding recordings to the particular series along they get populated to the channel's program schedule. This means that the user's recording quota is not taken into account when adding the automated recording request. The automated recording request will keep on running as a background process if the user's recording quota allows it. If the quota gets full, the process will not add new recordings anymore. Respectively when some quota is freed, the process will continue adding the automated recordings based on the user's stored automated recording rules.
Exceeded user recording limit
There are two available strategies to handling exceeding of recording limit.
By default, when a user reaches the recording limit, the system blocks new recordings being added to the user (and its profiles), until user free up enough space for the new recording.
Alternatively, it is possible to configure the system to auto delete exceeded recordings. In this mode, instead of blocking new recordings, a cleaner is scheduled to run daily. The cleaner automatically deletes users' exceeded recordings until they are again below the limit.
Delete priority: Firstly non-favorite recordings from oldest to newest. If threshold is not met, then favorite recordings are deleted from oldest to newest.