# 🎵 TikTok Scraper & Downloader Library
[](https://tiktok.com/@xbibzofficiall)
@xbibzlibrary/tiktokscrap
🚀 Powerful, Modern & Feature-Rich TikTok Scraping & Downloading Library Built with TypeScript
---
## ✨ Features
🎬 Video Scraping
- ✓ Scrape by URL or ID
- ✓ Get trending videos
- ✓ Recommended videos
- ✓ Full metadata extraction
📸 Photo Scraping
- ✓ Multi-photo post support
- ✓ High-quality images
- ✓ Photo trends & recommendations
- ✓ Complete metadata
👤 User Scraping
- ✓ Profile information
- ✓ User posts & likes
- ✓ Follower statistics
- ✓ Feed pagination
#️⃣ Hashtag Scraping
- ✓ Hashtag feed
- ✓ Trending hashtags
- ✓ Challenge data
- ✓ View count & stats
⬇️ Smart Downloading
- ✓ Video & photo downloads
- ✓ Progress tracking
- ✓ Custom output paths
- ✓ Batch downloads
🛠️ Advanced Features
- ✓ Proxy support
- ✓ Retry mechanism
- ✓ Error handling
- ✓ Custom headers
---
## 📦 Installation
```bash
# Using npm
npm install @xbibzlibrary/tiktokscrap
# Using yarn
yarn add @xbibzlibrary/tiktokscrap
# Using pnpm
pnpm add @xbibzlibrary/tiktokscrap
```
---
## 🚀 Quick Start
```typescript
import TikTokScrap from '@xbibzlibrary/tiktokscrap';
// Initialize the library
const tiktok = new TikTokScrap();
// Get video information
const video = await tiktok.getVideoByUrl('https://www.tiktok.com/@username/video/1234567890');
if (video.success) {
console.log('📹 Video Title:', video.data.text);
console.log('👤 Author:', video.data.author.nickname);
console.log('❤️ Likes:', video.data.stats.digg);
// Download the video
await tiktok.downloadVideo(video.data, {
outputDir: './downloads',
progressCallback: (progress) => console.log(`⏬ Progress: ${progress}%`)
});
}
```
---
## 📖 Usage
### 🎬 Video Operations
Get Video by URL
```typescript
const result = await tiktok.getVideoByUrl('https://www.tiktok.com/@user/video/123456');
if (result.success) {
console.log('Video Data:', result.data);
// Access: id, text, author, music, stats, videoMeta, hashtags, etc.
}
```
Get Video by ID
```typescript
const result = await tiktok.getVideoById('1234567890123456789');
if (result.success) {
const video = result.data;
console.log(`Title: ${video.text}`);
console.log(`Duration: ${video.videoMeta.duration}s`);
console.log(`Views: ${video.stats.play}`);
}
```
Get Trending Videos
```typescript
const trending = await tiktok.getVideoTrends(20); // Get top 20
if (trending.success) {
trending.data.forEach(video => {
console.log(`🔥 ${video.text} - ${video.stats.play} views`);
});
}
```
Get Recommended Videos
```typescript
const recommended = await tiktok.getRecommendedVideos('videoId', 10);
if (recommended.success) {
console.log(`Found ${recommended.data.length} recommended videos`);
}
```
### 📸 Photo Operations
Get Photo by URL
```typescript
const result = await tiktok.getPhotoByUrl('https://www.tiktok.com/@user/photo/123456');
if (result.success) {
const photo = result.data;
console.log(`Photos in post: ${photo.covers.length}`);
photo.covers.forEach((cover, i) => {
console.log(`Photo ${i + 1}: ${cover.url}`);
});
}
```
Download Photos
```typescript
const photoResult = await tiktok.getPhotoByUrl('https://www.tiktok.com/@user/photo/123456');
if (photoResult.success) {
const downloaded = await tiktok.downloadPhoto(photoResult.data, {
outputDir: './photos',
filename: 'my-tiktok-photo',
progressCallback: (progress) => {
console.log(`📥 Downloading: ${progress}%`);
}
});
if (downloaded.success) {
console.log(`✅ Downloaded ${downloaded.data.length} photos!`);
}
}
```
### 👤 User Operations
Get User Profile
```typescript
const user = await tiktok.getUserByUsername('@username');
if (user.success) {
const profile = user.data;
console.log(`Name: ${profile.nickname}`);
console.log(`Followers: ${profile.fans}`);
console.log(`Following: ${profile.following}`);
console.log(`Total Likes: ${profile.heart}`);
console.log(`Videos: ${profile.video}`);
}
```
Get User Videos
```typescript
const videos = await tiktok.getUserVideos('@username', 0, 30);
if (videos.success) {
videos.data.forEach(video => {
console.log(`📹 ${video.text}`);
console.log(` ❤️ ${video.stats.digg} | 💬 ${video.stats.comment}`);
});
}
```
Get User Feed (Videos & Photos)
```typescript
const feed = await tiktok.getUserFeed({
username: '@username',
cursor: 0,
count: 20,
type: 'post' // or 'like'
});
if (feed.success) {
console.log(`Found ${feed.data.length} posts`);
}
```
### #️⃣ Hashtag Operations
Get Hashtag Info
```typescript
const hashtag = await tiktok.getHashtagByName('#fyp');
if (hashtag.success) {
const tag = hashtag.data;
console.log(`Title: ${tag.title}`);
console.log(`Views: ${tag.viewCount}`);
console.log(`Description: ${tag.description}`);
}
```
Get Hashtag Videos
```typescript
const videos = await tiktok.getHashtagVideos('#dance', 0, 50);
if (videos.success) {
console.log(`Found ${videos.data.length} videos with #dance`);
}
```
Get Trending Hashtags
```typescript
const trending = await tiktok.getTrendingHashtags(10);
if (trending.success) {
trending.data.forEach((tag, i) => {
console.log(`${i + 1}. #${tag.name} - ${tag.viewCount} views`);
});
}
```
### ⬇️ Download Operations
Download Video
```typescript
const video = await tiktok.getVideoByUrl('https://www.tiktok.com/@user/video/123');
if (video.success) {
const download = await tiktok.downloadVideo(video.data, {
outputDir: './downloads',
filename: 'my-video.mp4',
progressCallback: (progress) => {
console.log(`⏬ ${progress}%`);
}
});
if (download.success) {
console.log(`✅ Saved to: ${download.data}`);
}
}
```
Download Video by URL (Direct)
```typescript
const download = await tiktok.downloadVideoByUrl(
'https://www.tiktok.com/@user/video/123',
{
outputDir: './downloads',
progressCallback: (progress) => console.log(`${progress}%`)
}
);
```
Batch Download
```typescript
const videos = await tiktok.getUserVideos('@username', 0, 10);
if (videos.success) {
for (const video of videos.data) {
await tiktok.downloadVideo(video, {
outputDir: './batch-downloads',
filename: `${video.id}.mp4`
});
}
}
```
---
## 🎯 API Documentation
### Constructor Options
```typescript
interface TikTokScrapOptions {
timeout?: number; // Request timeout (default: 30000ms)
retries?: number; // Retry attempts (default: 3)
userAgent?: string; // Custom user agent
proxy?: { // Proxy configuration
host: string;
port: number;
auth?: {
username: string;
password: string;
};
};
headers?: Record; // Custom headers
}
// Usage
const tiktok = new TikTokScrap({
timeout: 60000,
retries: 5,
proxy: {
host: '127.0.0.1',
port: 8080
}
});
```
### Response Structure
```typescript
interface TikTokScrapResult {
success: boolean; // Request success status
data?: T; // Response data (if successful)
error?: string; // Error message (if failed)
message?: string; // Status message
}
```
### Video Data Structure
```typescript
interface TikTokVideo {
id: string; // Video ID
text: string; // Video caption/description
createTime: number; // Upload timestamp
author: TikTokUser; // Author information
music: { // Music information
id: string;
title: string;
author: string;
playUrl: string;
};
stats: { // Video statistics
digg: number; // Likes
share: number; // Shares
comment: number; // Comments
play: number; // Views
};
videoMeta: { // Video metadata
width: number;
height: number;
duration: number;
cover: string; // Cover image URL
};
downloadAddr: string; // Direct download URL
hashtags: Array<{}>; // Hashtags used
// ... more fields
}
```
---
## 💡 Advanced Examples
### 🔄 Error Handling
```typescript
try {
const video = await tiktok.getVideoByUrl('invalid-url');
if (!video.success) {
console.error('Error:', video.error);
console.error('Message:', video.message);
}
} catch (error) {
console.error('Exception:', error.message);
}
```
### 🔁 Pagination
```typescript
let cursor = 0;
let allVideos = [];
while (cursor < 100) {
const result = await tiktok.getUserVideos('@username', cursor, 20);
if (!result.success || result.data.length === 0) break;
allVideos.push(...result.data);
cursor += 20;
// Rate limiting
await new Promise(resolve => setTimeout(resolve, 1000));
}
console.log(`Total videos collected: ${allVideos.length}`);
```
### 📊 Statistics Collection
```typescript
const user = await tiktok.getUserByUsername('@username');
if (user.success) {
const videos = await tiktok.getUserVideos('@username', 0, 100);
if (videos.success) {
const totalLikes = videos.data.reduce((sum, v) => sum + v.stats.digg, 0);
const totalViews = videos.data.reduce((sum, v) => sum + v.stats.play, 0);
const avgLikes = totalLikes / videos.data.length;
console.log(`📊 Statistics for @${user.data.uniqueId}`);
console.log(`Total Videos: ${videos.data.length}`);
console.log(`Total Likes: ${totalLikes.toLocaleString()}`);
console.log(`Total Views: ${totalViews.toLocaleString()}`);
console.log(`Average Likes: ${avgLikes.toFixed(0)}`);
}
}
```
### 🎯 Custom Configuration
```typescript
const tiktok = new TikTokScrap({
timeout: 60000,
retries: 5,
headers: {
'Accept-Language': 'id-ID,id;q=0.9',
'Custom-Header': 'value'
}
});
// Update configuration later
tiktok.updateOptions({
timeout: 45000,
retries: 3
});
// Get current configuration
const config = tiktok.getOptions();
console.log('Current config:', config);
```
### 🎨 Progress Bar Example
```typescript
import cliProgress from 'cli-progress';
const progressBar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
const video = await tiktok.getVideoByUrl('https://...');
if (video.success) {
progressBar.start(100, 0);
await tiktok.downloadVideo(video.data, {
outputDir: './downloads',
progressCallback: (progress) => {
progressBar.update(progress);
}
});
progressBar.stop();
console.log('✅ Download complete!');
}
```
---
## 🏗️ Architecture
```
@xbibzlibrary/tiktokscrap
├── 🎬 Scrapers
│ ├── VideoScraper → Video content scraping
│ ├── PhotoScraper → Photo content scraping
│ ├── UserScraper → User profile & feed
│ └── HashtagScraper → Hashtag & trends
│
├── ⬇️ Downloaders
│ ├── VideoDownloader → Video file downloads
│ └── PhotoDownloader → Photo downloads
│
├── 🛠️ Utilities
│ ├── HttpClient → HTTP requests & retries
│ ├── Parser → HTML/JSON parsing
│ ├── Validator → Input validation
│ └── Logger → Logging system
│
└── 🎯 Core
├── Types → TypeScript definitions
└── Errors → Custom error classes
```
---
## 🤝 Contributing
Contributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest new features
- 🔧 Submit pull requests
- 📖 Improve documentation
---
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
## 👨💻 Author
### Xbibz Official
💖 If this library helps you, consider supporting me!
---
## ⚠️ Disclaimer
This library is for **educational purposes only**. Please respect TikTok's Terms of Service and use this library responsibly. The author is not responsible for any misuse of this library.
---
🌟 Star this project if you find it useful! 🌟
Made with ❤️ by Xbibz Official
---
## 📊 Project Stats
