mebox-extractor
Version:
🎬 A powerful and type-safe video metadata extractor for YouTube and Bilibili platforms with full TypeScript support
314 lines (232 loc) • 8.44 kB
Markdown
# 🎬 mebox-extractor
> A powerful and type-safe video metadata extractor for YouTube and Bilibili platforms with full TypeScript support
[](https://badge.fury.io/js/mebox-extractor)
[](https://www.typescriptlang.org/)
[](https://choosealicense.com/licenses/mit/)
[](https://nodejs.org/)
## ✨ 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
```bash
npm install mebox-extractor
```
### Basic Usage
```typescript
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
```typescript
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
```typescript
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
```typescript
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:
```typescript
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:
```typescript
interface DownloadFormat {
mimeType: string // e.g., 'video/mp4', 'audio/mp4'
url: string // Direct download URL
}
```
### Subtitles
```typescript
interface SubTitleItem {
start: number // Start time in seconds
end: number // End time in seconds
text: string // Subtitle text
}
type SubTitles = SubTitleItem[]
```
## ⚙️ Configuration Options
```typescript
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:
```typescript
const metadata = await extract(youtubeUrl, {
cookies: {
'session_token': 'your-session-token'
}
})
```
### Bilibili
For higher quality videos or member-only content:
```typescript
const metadata = await extract(bilibiliUrl, {
cookies: {
'SESSDATA': 'your-sessdata-cookie',
'buvid3': 'your-buvid3-cookie'
}
})
```
## 🛠️ Advanced Usage
### Using with Different Module Systems
#### ES Modules
```javascript
import { extract } from 'mebox-extractor'
```
#### CommonJS
```javascript
const { extract } = require('mebox-extractor')
```
#### TypeScript
```typescript
import { extract, VideoMetadataSchema, ExtractorOptions } from 'mebox-extractor'
```
### Utility Functions
The package also exports utility functions for URL analysis:
```typescript
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
```bash
git clone https://github.com/one2x/mebox-extractor.git
cd mebox-extractor
npm install
```
### Scripts
```bash
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
```bash
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**
```bash
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](LICENSE) file for details.
## 🙏 Acknowledgments
- [youtubei.js](https://github.com/LuanRT/YouTube.js) - YouTube API implementation
- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) - XML parsing for subtitles
- All contributors who help improve this project