🎬 mebox-extractor

A powerful and type-safe video metadata extractor for YouTube and Bilibili platforms with full TypeScript support

✨ Features

• 🎯 Simple API: One function to extract video metadata from multiple platforms
• 🔒 Type Safe: Full TypeScript support with comprehensive type definitions
• 🌐 Multi-Platform: Support for YouTube and Bilibili video platforms
• 📺 Rich Metadata: Extract title, description, thumbnail, duration, subtitles, and download URLs
• ⚡ Fast & Reliable: Built-in retry mechanism and error handling
• 📦 Dual Package: Supports both ESM and CommonJS
• 🧪 Well Tested: Comprehensive test suite with 66+ test cases
• 🔧 Zero Config: Works out of the box with sensible defaults

Resolution Support

| Platform | 4K | 1080p | 720p | 360p | |----------|----|----|----|----| | YouTube | ✅ | ✅ | ✅ | ✅ | | Bilibili | ⚠️ | ✅ | ✅ | ✅ |

🚀 Quick Start

Installation

npm install mebox-extractor

Basic Usage

import { extract } from 'mebox-extractor'

// Extract YouTube video metadata
const metadata = await extract("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

console.log(metadata.title)       // Video title
console.log(metadata.duration)    // Duration in seconds
console.log(metadata.thumbnail)   // Thumbnail URL
console.log(metadata.downloadURL) // Download URL

📖 Usage Examples

YouTube Videos

import { extract } from 'mebox-extractor'

// Standard YouTube URL
const youtubeMetadata = await extract("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

// YouTube Shorts
const shortsMetadata = await extract("https://youtu.be/dQw4w9WgXcQ")

// With custom options
const hdMetadata = await extract("https://www.youtube.com/watch?v=dQw4w9WgXcQ", {
  resolution: '1080p',
  cookies: {
    'session': 'your-session-cookie'
  }
})

Bilibili Videos

import { extract } from 'mebox-extractor'

// Bilibili video
const bilibiliMetadata = await extract("https://www.bilibili.com/video/BV1GJ411x7h7")

// With authentication for higher quality
const hqMetadata = await extract("https://www.bilibili.com/video/BV1GJ411x7h7", {
  resolution: '1080p',
  cookies: {
    'SESSDATA': 'your-sessdata-cookie'
  }
})

Error Handling

import { extract } from 'mebox-extractor'

try {
  const metadata = await extract("https://unsupported-site.com/video")
} catch (error) {
  if (error.message.includes('not supported')) {
    console.log('This platform is not supported')
  } else if (error.message.includes('video id is not found')) {
    console.log('Invalid video URL')
  }
}

📊 Response Format

The extract function returns a VideoMetadataSchema object:

interface VideoMetadataSchema {
  website: 'youtube' | 'bilibili'
  videoId: string              // Platform-specific video ID
  url: string                  // Original video URL
  downloadURL: string | [DownloadFormat, DownloadFormat]
  previewURL: string           // Preview/streaming URL
  fps: number                  // Frames per second
  title: string                // Video title
  description: string          // Video description
  thumbnail: string            // Thumbnail image URL
  duration: number             // Duration in seconds
  subtitles?: SubTitles        // Subtitle data (if available)
}

Download Formats

For Bilibili videos, downloadURL is an array with separate video and audio streams:

interface DownloadFormat {
  mimeType: string             // e.g., 'video/mp4', 'audio/mp4'
  url: string                  // Direct download URL
}

Subtitles

interface SubTitleItem {
  start: number                // Start time in seconds
  end: number                  // End time in seconds
  text: string                 // Subtitle text
}

type SubTitles = SubTitleItem[]

⚙️ Configuration Options

interface ExtractorOptions {
  resolution?: '4k' | '1080p' | '720p' | '360p'  // Preferred resolution
  cookies?: Record<string, string>                // Authentication cookies
}

Note: Higher resolutions may require authentication cookies.

🔐 Authentication

YouTube

For private or age-restricted videos, provide session cookies:

const metadata = await extract(youtubeUrl, {
  cookies: {
    'session_token': 'your-session-token'
  }
})

Bilibili

For higher quality videos or member-only content:

const metadata = await extract(bilibiliUrl, {
  cookies: {
    'SESSDATA': 'your-sessdata-cookie',
    'buvid3': 'your-buvid3-cookie'
  }
})

🛠️ Advanced Usage

Using with Different Module Systems

ES Modules

import { extract } from 'mebox-extractor'

CommonJS

const { extract } = require('mebox-extractor')

TypeScript

import { extract, VideoMetadataSchema, ExtractorOptions } from 'mebox-extractor'

Utility Functions

The package also exports utility functions for URL analysis:

import { convertURLToWebsiteKey, getVideoIdByURL } from 'mebox-extractor'

// Check if URL is supported
const website = convertURLToWebsiteKey('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
console.log(website) // 'youtube'

// Extract video ID
const videoId = getVideoIdByURL('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
console.log(videoId) // 'dQw4w9WgXcQ'

🔧 Development

Setup

git clone https://github.com/one2x/mebox-extractor.git
cd mebox-extractor
npm install

Scripts

npm run build        # Build the project
npm run test         # Run tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage# Run tests with coverage
npm run typecheck    # Type checking
npm run dev          # Development mode with watch
npm run clean        # Clean build artifacts

Testing

The project includes comprehensive tests:

• Unit Tests: 66+ test cases covering all functionality
• Integration Tests: End-to-end testing with mocked data
• Type Tests: TypeScript type checking and validation

npm test             # Run all tests
npm run test:coverage # Run with coverage report

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Type Safety: No any types allowed
• Test Coverage: Add tests for new features
• Documentation: Update README for API changes
• Code Style: Follow TypeScript best practices and existing code patterns

📝 Changelog

v0.0.1

• ✨ Initial release
• 🎯 Support for YouTube and Bilibili
• 🔒 Full TypeScript support
• 📦 ESM and CommonJS compatibility
• 🧪 Comprehensive test suite
• 📚 Complete documentation

🐛 Troubleshooting

Common Issues

Module Import Errors

Error: Cannot use import statement outside a module

• Solution: Use the CommonJS export (require) or ensure your project supports ES modules

Network Timeouts

• The extractor includes automatic retry logic (3 attempts)
• For persistent issues, check your network connection and any firewall restrictions

Rate Limiting

• YouTube and Bilibili may rate limit requests
• Consider adding delays between requests for bulk operations

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• youtubei.js - YouTube API implementation
• fast-xml-parser - XML parsing for subtitles
• All contributors who help improve this project