Skip to main content
Vimeo is a professional video hosting platform with high-quality content. OpenTogetherTube supports individual Vimeo videos through their oEmbed API.

​
Features

Individual Videos Only

Vimeo support is limited to individual video URLs. Collections, playlists, and channels are not supported.

​
Supported URL Format

Vimeo URLs must follow this exact pattern: 
https://vimeo.com/VIDEO_ID

​
Valid Examples

https://vimeo.com/123456789
https://www.vimeo.com/987654321

​
Invalid Examples

https://vimeo.com/channels/staffpicks/123456789  ❌
https://vimeo.com/user/username                   ❌
https://vimeo.com/showcase/123456789              ❌
The video ID must be numeric and directly after vimeo.com/ in the URL path.

​
API Access

No API key required! Vimeo support uses the public oEmbed API which doesn’t require authentication.
The adapter uses Vimeo’s oEmbed endpoint: 
https://vimeo.com/api/oembed.json?url=VIDEO_URL

​
Metadata Extraction

The following video metadata is extracted from Vimeo:
PropertySourceDescription
TitletitleVideo title
DescriptiondescriptionFull video description
Thumbnailthumbnail_urlVideo thumbnail image
DurationdurationVideo length in seconds

​
Example Response

{
  "title": "Example Video",
  "description": "This is an example video description",
  "thumbnail_url": "https://i.vimeocdn.com/video/123456789_640.jpg",
  "duration": 180
}

​
Limitations

Vimeo videos have several important limitations:

​
Embedding Restrictions

Vimeo allows video creators to disable embedding. If a video has embedding disabled:
  • API request returns HTTP 403 Forbidden
  • Video cannot be played in OpenTogetherTube
  • Error message: “Embedding for this video is disabled!”
This is implemented in vimeo.ts:66-70: 
if (err.response && err.response.status === 403) {
  log.error("Failed to get video info: Embedding for this video is disabled!");
}

​
No Collections

Unlike YouTube, Vimeo support does not include:
  • ❌ Playlists
  • ❌ Showcases
  • ❌ Channels
  • ❌ User profiles
  • ❌ Video albums
The Vimeo adapter does not support searching for videos. Users must provide direct video URLs.

​
Not Cache Safe

Vimeo metadata has isCacheSafe: false, meaning:
  • Video metadata is fetched fresh each time
  • Metadata is not stored long-term in the database
  • Ensures up-to-date information but increases API calls

​
Privacy & Domain Support

OpenTogetherTube can play both public and unlisted Vimeo videos, as long as embedding is enabled.

​
Supported Privacy Settings

  • ✅ Public videos
  • ✅ Unlisted videos (with link)
  • ❌ Private videos (require password or permission)

​
Supported Domains

  • vimeo.com
  • www.vimeo.com
Custom domains or Vimeo staff picks may not work correctly.

​
Error Handling

Common errors you may encounter:
Cause: Video creator disabled embedding for this videoSolution: This video cannot be played in OTT. Try a different video or ask the creator to enable embedding.
Cause: Video ID is not numeric or URL format is incorrectSolution: Verify the URL is in the format https://vimeo.com/NUMERIC_ID
Cause: Video doesn’t exist or has been deletedSolution: Check that the video ID is correct and the video is still available

​
Configuration

Vimeo support works out-of-the-box with no configuration needed: 
# No Vimeo-specific configuration required

​
Video ID Validation

The adapter validates video IDs before making API requests: 
if (!/^\d+$/.test(videoId)) {
  throw new InvalidVideoIdException(this.serviceId, videoId);
}
Video IDs must contain only digits. Any non-numeric characters will be rejected.

​
Implementation Details

The Vimeo adapter is implemented in server/services/vimeo.ts and is one of the simplest service adapters:
  • File size: Only 74 lines of code
  • API Client: Uses axios with base URL https://vimeo.com/api/oembed.json
  • Dependencies: No external service dependencies
  • Cache: Does not use Redis or database caching
Key methods:
  • canHandleURL(): Checks for vimeo.com domain and numeric path (line 30-33)
  • getVideoId(): Extracts the last segment of the URL path (line 39-42)
  • fetchVideoInfo(): Makes oEmbed API request (line 44-72)
  • isCollectionURL(): Always returns false (line 35-37)
The adapter is marked as not cache-safe (isCacheSafe: false) because Vimeo video metadata and availability can change frequently.

​
Comparison with YouTube

FeatureYouTubeVimeo
API Key Required✅ Yes❌ No
Individual Videos✅ Yes✅ Yes
Playlists✅ Yes❌ No
Channels✅ Yes❌ No
Search✅ Yes❌ No
Cache Safe✅ Yes❌ No
Embedding ControlPlatform-widePer-video

​
Usage Example

1

Find a Vimeo Video

Browse Vimeo and find a video you want to watch
2

Copy the URL

Copy the URL from your browser (format: https://vimeo.com/123456789)
3

Add to Room

Paste the URL into the “Add video” input in your OTT room
4

Play

The video will be added to the queue and start playing automatically

​
Troubleshooting

Video won't play

Check if embedding is enabled. Try playing the video on Vimeo.com first.

Wrong video loads

Verify the video ID is correct. Vimeo IDs are numeric only.

Missing metadata

Some Vimeo videos may have incomplete metadata. This is normal.

Slow loading

Vimeo videos are not cached, so loading time depends on Vimeo’s API response.

​
Best Practices

When sharing Vimeo videos with your OTT room:
  • Use the simplest URL format possible
  • Verify the video allows embedding before adding
  • Check video availability if it fails to load

Build docs developers (and LLMs) love

Get started for freeTalk to us