This feature requires an Enterprise plan with the Events feature added.
This article contains information about retrieving details about Live Events using the Vimeo Live API. More details are available in the API Reference.
In this article:
- Create a live event
- Create a custom embed for an event or video
- Retrieve details for a Recurring Event
- After the event - Clips within Recurring Events
- Retrieve details for individual video clips or VODs
Create a live event
View our guide to creating a live event with the API at Vimeo Developers: 'Create a live event'.
Create a custom embed for an event or video
If you wish to create a customized embed for your Vimeo event or video, there are two methods for doing so:
- You can use Player SDK. See our developer reference for more details.
- You can use player.js as discussed in this readme.
Retrieve details for a Recurring Event
During a live event, we recommend embedding the event iframe rather than the underlying individual video clip to ensure the same embed code will continue to function for the current and reoccurring events.
Use the API to retrieve the event by ID:
https://api.vimeo.com/live_events/{event_id}
From the response, then retrieve the embeddable iframe code from embed.html
Is chat enabled? "chat_enabled" true/false
If true, "chat_embed_code" contains the embeddable iframe code.
A few details of the event response you may need to know for your application:
- "stream privacy" reflects the level of privacy
- "embed": "public","whitelist", or "private". Private will not be embeddable by partners
- "stream_password" reflects the password for the stream
- "badges" contains information about the clip to inform the player:
- "live" tells us "streaming":true/false or archived true/false
- "vod" tells us it's vod or not.
Detailed documentation is available in the API Reference.
After the event - Clips within Recurring Events
Post-event, the player embed will display one of three things:
- The latest VOD clip from the previous session
- A message that the (next) stream is not yet started
- A new event, if the recurring event is used to stream again.
Reliable display of the appropriate VOD clip will require embedding the individual clip vs the event. Obtain the ID and data of the individual clip from the events API response.
The Recurring Event contains two relevant objects. The object to reference depends on when you are retrieving the data.
- live_clips - (after the stream). An array of all completed video clips from the event, containing the video ID and the epoch timestamp for when the event was streamed.
- streamable_clip - (before/during the stream). This is the active clip before/during a stream. The id and embed code correspond to the individual clip during the stream as well as to the resulting VOD.
After a stream is stopped, its clip information moves into the live_clips array, and streamable_clip will change, containing the information for the next clip to stream.
Retrieve details for individual video clips
You can reach a video clip directly by ID. This method is used for accessing details for a video clip or individual VOD. The ID and embed will not change when Live converts to VOD.
Details of an individual video clip:
https://api.vimeo.com/videos/{video_id}
- “link” is the url
- "embed" contains embed properties for the clip
- "html" is the iframe source for the clip
- "badges" contains information about the clip to inform the player:
- "live" tells us "streaming":true/false or archived true/false
- "vod" tells us it's vod or not.
- "chat_embed_code" is embed code for chat. May be inherited if recurring live event (RLE).
- "chat_enabled" is true/false. May be inherited if recurring live event (RLE).
- "live" contains information for streaming, and will include information about the parent event container, if any
Details are available in the API Reference.