# Vimeo Downloader & Advanced Player API

[![npm version](https://img.shields.io/npm/v/vimeo.svg)](https://www.npmjs.com/package/vimeo)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Downloads](https://img.shields.io/npm/dm/vimeo.svg)](https://www.npmjs.com/package/vimeo)

**The most advanced Node.js tool to download Vimeo videos, extract metadata, HLS/DASH streams, subtitles, and control the Vimeo Player API.**

Whether you need to **download private Vimeo videos**, extract **1080p/4K MP4 links**, or build a custom **Vimeo Player controller**, this library handles it all with a simple CLI and a powerful API.

---

## 🚀 Key Features

*   🔎 **Auto-detects videos on any Vimeo page**: Easily extracts video details from any Vimeo URL.
*   📺 **Supports embedded players & showcases**: Handles standard video URLs and embedded contexts via Referer support.
*   ⬇️ **Download in Full HD and up to 4K when available**: Automatically selects the highest quality MP4 stream.
*   🖼 **Thumbnail preview & video metadata extraction**: Get full JSON details including duration, author, and thumbnails.
*   ⚡ **Fast & reliable downloads (no re-encoding)**: Direct stream downloading for maximum speed.
*   🛡 **Privacy-first design (no tracking, no ads)**: Open source, clean code with no analytics or bloat.
*   🔄 **Regular updates & community support**: Actively maintained to adapt to Vimeo's changes.
*   🎮 **Advanced Player Dashboard**: Control the Vimeo Player API (Seek, Speed, Color) via a local interface.
*   📝 **Subtitles & Captions**: One-click extraction of .vtt subtitle files.

---

## 📦 Installation

Install globally to use the CLI, or locally for your project.

```bash
# Global installation for CLI usage
npm install -g vimeo

# Local installation for Node.js projects
npm install vimeo
```

---

## 💻 CLI Usage (Command Line Interface)

The `vimeo-dl` command is your all-in-one tool for interacting with Vimeo.

### 1. Download a Video
Automatically downloads the best quality available.
```bash
vimeo-dl https://vimeo.com/76979871
```

### 2. Choose Quality & Output
Select specific resolutions (e.g., `720p`, `1080p`) and custom save paths.
```bash
vimeo-dl https://vimeo.com/76979871 --quality 720p --output ./my-videos
```

### 3. Get Video Metadata (JSON)
Extract raw JSON data (URLs, HLS links, author info) for use in other scripts.
```bash
vimeo-dl https://vimeo.com/76979871 --info
```

### 4. Download Private Videos
If a video is restricted to a specific domain, provide the `Referer` header.
```bash
vimeo-dl https://vimeo.com/76979871 --referer "https://example.com/"
```

### 5. Launch Player Dashboard 🆕
Open a local control panel to test the Vimeo Player API (Seek, Speed, Color, Events). Now includes a download button!
```bash
vimeo-dl play https://vimeo.com/76979871
```
For private videos with referer:
```bash
vimeo-dl play https://vimeo.com/76979871 --referer "https://example.com/"
```

**Player Features:**
- Full Vimeo Player API control (play, pause, seek, speed, volume)
- Event logging and debugging
- Download button for direct browser downloads
- Responsive design with advanced controls

---

## 🛠️ Node.js API Usage

Integrate Vimeo downloading capabilities directly into your application.

### Basic Metadata Extraction
```javascript
const vimeo = require('vimeo');

async function getInfo() {
  const data = await vimeo("https://vimeo.com/76979871");
  console.log(data);
}
getInfo();
```

### Advanced: Downloading & Streams
Access HLS streams, subtitles, and download files with progress tracking.

```javascript
const { getVideoDetails, downloadFile } = require('vimeo');

async function processVideo() {
  try {
    // 1. Fetch Video Details
    const details = await getVideoDetails("https://vimeo.com/76979871", {
      referer: "https://my-protected-site.com/"
    });

    console.log(`Video Title: ${details.meta.title}`);
    console.log(`HLS Stream: ${details.hls ? details.hls.url : 'N/A'}`);

    // 2. List Available Subtitles
    if (details.subtitles.length > 0) {
      console.log('Subtitles found:', details.subtitles.map(s => s.lang));
    }

    // 3. Download the Best Quality MP4
    const bestFormat = details.formats[0]; // Formats are sorted by quality
    if (bestFormat) {
      console.log(`Downloading ${bestFormat.quality} (${bestFormat.width}x${bestFormat.height})...`);
      
      await downloadFile(bestFormat.url, `./${details.meta.id}.mp4`, (pct, downloaded, total) => {
        console.log(`Progress: ${pct.toFixed(1)}%`);
      });
      
      console.log('Download complete!');
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

processVideo();
```

---

## ❓ Frequently Asked Questions (FAQ)

### How do I download private Vimeo videos?
Private videos often check the `Referer` header. You can bypass this by using the `--referer` flag in the CLI or the `referer` option in the API.
```bash
vimeo-dl https://vimeo.com/76979871 --referer "https://website-where-video-is-embedded.com"
```

### Can I get the HLS (.m3u8) or DASH (.mpd) links?
Yes! Use the `--info` flag in the CLI or check the `.hls` and `.dash` properties in the API response. These are useful for playing videos in custom players (like Video.js or Hls.js).

### Does this tool support 4K downloads?
Yes. If the video owner has uploaded a 4K version and Vimeo has processed it as a progressive MP4, it will be detected and prioritized as the best quality.

### How can I extract Vimeo subtitles?
The API returns a `subtitles` array containing URLs to `.vtt` files for all available languages. You can fetch these URLs to save the subtitles/captions.

---

## 📄 License
This project is licensed under the ISC License.

---
*Keywords: vimeo downloader, download vimeo videos, vimeo to mp4, vimeo private downloader, nodejs vimeo api, vimeo cli, save vimeo video, extract vimeo subtitles, m3u8 downloader*