mediasnap

mediasnap is a high-performance programmatic wrapper package for Node.js servers (e.g. NestJS, Express) around the open-source universalDownloader project. It strips away the HTTP/REST routing layer of the original project and exposes pure JavaScript functions for detecting platforms and downloading media from various platforms.

Supported Platforms

• TikTok
• Instagram
• Facebook
• Twitter (X)
• YouTube
• Reddit
• Pinterest
• Threads
• LinkedIn
• Snapchat
• Soundcloud
• Spotify
• Tumblr
• Douyin
• Kuaishou
• Dailymotion
• Bluesky
• CapCut
• TeraBox

Installation

npm install mediasnap

Usage

Importing in Another Project

ES Modules (TypeScript / Modern Node.js)

import { downloadMedia, detectPlatform } from 'mediasnap';

CommonJS (Standard Node.js)

const { downloadMedia, detectPlatform } = require('mediasnap');

Platform Detection

Detect the downloader platform from a URL:

import { detectPlatform } from 'mediasnap';

const platform = detectPlatform('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(platform); // 'youtube'

Media Downloading

Download media directly using the unified downloadMedia(url) entry point:

import { downloadMedia } from 'mediasnap';

async function run() {
  const result = await downloadMedia('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
  
  if (result.success) {
    console.log('Platform:', result.platform);
    console.log('Title:', result.title);
    console.log('Media items:', result.media);
  } else {
    console.error('Error:', result.error);
  }
}

run();

Command Line Execution

You can test the package directly from your shell using Node's evaluation flag:

node -e "const { downloadMedia } = require('mediasnap'); downloadMedia('https://www.youtube.com/watch?v=dQw4w9WgXcQ').then(console.log);"

Return Structure

The downloadMedia function returns a Promise<DownloadResult> with the following shape:

interface AdaptedMediaItem {
  type: 'video' | 'audio' | 'image';
  url: string;                 // direct download URL
  quality: string | null;      // label (e.g. '1080p', '128kbps', 'original')
  format: string | null;       // normalized lowercase format (e.g. 'mp4', 'mp3', 'jpg')
  sizeMB?: number | null;      // estimated file size in MB if available
}

interface DownloadResult {
  success: boolean;            // true if the download succeeded, false otherwise
  platform: string;            // the detected platform name (e.g., 'youtube', 'tiktok', etc.) or 'unknown'
  title: string | null;        // post / media title
  description: string | null;  // post description or caption
  thumbnail: string | null;    // video thumbnail / image preview url
  duration: string | number | null; // duration if available
  media: AdaptedMediaItem[];   // list of extracted media items, sorted descending by quality
  error?: string;              // details of the error if success is false
}

NestJS Integration Example

// media.service.ts
import { Injectable } from '@nestjs/common';
import { downloadMedia, DownloadResult } from 'mediasnap';

@Injectable()
export class MediaService {
  async download(url: string): Promise<DownloadResult> {
    return downloadMedia(url);
  }
}

Upstream Sync

To sync this wrapper package with upstream changes from universalDownloader:

npm run sync-upstream

Author & Credits

• Wrapped and package-maintained by Antigravity.
• Original downloader core logic and services created by milancodess (Milan).

License

MIT