@aitofy/youtube 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Aitofy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+DISCLAIMER: This software accesses YouTube's internal APIs which may violate
+YouTube's Terms of Service. This software is provided for educational and
+personal use only. The authors are not responsible for any misuse or
+consequences arising from the use of this software. Use at your own risk.

package/README.md

@@ -0,0 +1,278 @@
+# @aitofy/youtube
+
+> 🎬 Free YouTube utilities for Node.js - Get transcripts, channel videos, video info without API key
+
+[![npm version](https://badge.fury.io/js/@aitofy%2Fyoutube.svg)](https://www.npmjs.com/package/@aitofy/youtube)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚠️ Disclaimer
+
+This package accesses YouTube's internal APIs for educational and personal use. It may violate YouTube's Terms of Service. **Use at your own risk.** The authors are not responsible for any misuse or consequences.
+
+---
+
+## ✨ Features
+
+- 📝 **Get Transcripts** - Fetch video captions/subtitles in multiple formats
+- 📺 **List Channel Videos** - Get all videos from any YouTube channel
+- 🔍 **Search Videos** - Search YouTube programmatically
+- ℹ️ **Video Info** - Get metadata, views, duration, thumbnails
+- 🤖 **MCP Integration** - Use with Claude, ChatGPT, and other AI assistants
+- 🚫 **No API Key Required** - Works out of the box
+- 📦 **Zero Config** - Just install and use
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @aitofy/youtube
+```
+
+```bash
+yarn add @aitofy/youtube
+```
+
+```bash
+pnpm add @aitofy/youtube
+```
+
+---
+
+## 🚀 Quick Start
+
+### Get Transcript
+
+```typescript
+import { getTranscript, getTranscriptText } from '@aitofy/youtube';
+
+// Get transcript as segments
+const segments = await getTranscript('dQw4w9WgXcQ');
+console.log(segments);
+// [
+//   { start: 0.24, duration: 2.5, text: 'Never gonna give you up' },
+//   { start: 2.74, duration: 2.3, text: 'Never gonna let you down' },
+//   ...
+// ]
+
+// Get transcript as plain text
+const text = await getTranscriptText('dQw4w9WgXcQ');
+console.log(text);
+// "Never gonna give you up\nNever gonna let you down\n..."
+```
+
+### Get Channel Videos
+
+```typescript
+import { getChannelVideos } from '@aitofy/youtube';
+
+// By channel ID
+const videos = await getChannelVideos('UCsBjURrPoezykLs9EqgamOA');
+
+// By handle
+const videos = await getChannelVideos('@Fireship');
+
+// With options
+const videos = await getChannelVideos({
+  channel: '@Fireship',
+  limit: 50,
+  sortBy: 'popular', // 'newest' | 'oldest' | 'popular'
+});
+
+console.log(videos);
+// [
+//   { videoId: 'abc123', title: 'Video Title', viewCount: 12345, ... },
+//   ...
+// ]
+```
+
+### Search Videos
+
+```typescript
+import { searchVideos } from '@aitofy/youtube';
+
+const results = await searchVideos('nodejs tutorial');
+
+// With options
+const results = await searchVideos({
+  query: 'react hooks',
+  limit: 20,
+  sortBy: 'viewCount', // 'relevance' | 'date' | 'viewCount' | 'rating'
+});
+```
+
+### Get Video Info
+
+```typescript
+import { getVideoInfo } from '@aitofy/youtube';
+
+const info = await getVideoInfo('dQw4w9WgXcQ');
+console.log(info);
+// {
+//   videoId: 'dQw4w9WgXcQ',
+//   title: 'Rick Astley - Never Gonna Give You Up',
+//   duration: '3:33',
+//   viewCount: 1500000000,
+//   channelTitle: 'Rick Astley',
+//   thumbnails: { ... },
+//   ...
+// }
+```
+
+---
+
+## 📖 API Reference
+
+### Transcript Functions
+
+| Function | Description |
+|----------|-------------|
+| `getTranscript(videoId, options?)` | Get transcript segments |
+| `getTranscriptText(videoId, options?)` | Get transcript as plain text |
+| `getTranscriptSRT(videoId, options?)` | Get transcript as SRT subtitles |
+| `getTranscriptVTT(videoId, options?)` | Get transcript as WebVTT |
+| `listTranscripts(videoId)` | List available transcript languages |
+
+### Channel Functions
+
+| Function | Description |
+|----------|-------------|
+| `getChannelVideos(options)` | Get videos from a channel |
+| `getChannelInfo(channel)` | Get channel metadata |
+
+### Video Functions
+
+| Function | Description |
+|----------|-------------|
+| `getVideoInfo(videoId)` | Get detailed video info |
+| `getBasicVideoInfo(videoId)` | Get basic video info (faster) |
+| `searchVideos(query, options?)` | Search YouTube videos |
+
+---
+
+## 🔧 Options
+
+### Transcript Options
+
+```typescript
+interface FetchTranscriptOptions {
+  languages?: string[];      // Preferred languages, e.g. ['en', 'vi']
+  preferGenerated?: boolean; // Prefer auto-generated over manual
+}
+```
+
+### Channel Videos Options
+
+```typescript
+interface GetChannelVideosOptions {
+  channel: string;                    // Channel ID, URL, or @handle
+  limit?: number;                     // Max videos (default: 15)
+  sortBy?: 'newest' | 'oldest' | 'popular';
+  contentType?: 'videos' | 'shorts' | 'streams';
+}
+```
+
+### Search Options
+
+```typescript
+interface SearchOptions {
+  query: string;
+  limit?: number;
+  sortBy?: 'relevance' | 'date' | 'viewCount' | 'rating';
+}
+```
+
+---
+
+## 🎯 Use Cases
+
+- 📊 **Content Analysis** - Analyze video transcripts for SEO
+- 🤖 **AI/ML Training** - Collect transcripts for datasets
+- 📱 **App Development** - Build YouTube-related apps
+- 🔍 **Research** - Academic video content analysis
+- ♿ **Accessibility** - Generate subtitles for accessibility
+
+---
+
+## 🤖 MCP Integration (Claude, ChatGPT)
+
+Use YouTube tools directly in AI assistants via [Model Context Protocol](https://modelcontextprotocol.io/).
+
+### Setup for Claude Desktop
+
+1. Install the package globally:
+```bash
+npm install -g @aitofy/youtube
+```
+
+2. Add to Claude's config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "youtube": {
+      "command": "youtube-mcp"
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_youtube_transcript` | Get video transcript with timestamps |
+| `get_youtube_transcript_text` | Get transcript as plain text |
+| `list_youtube_transcripts` | List available languages |
+| `get_youtube_video_info` | Get video metadata |
+| `get_youtube_channel_videos` | List channel videos |
+| `get_youtube_channel_info` | Get channel info |
+| `search_youtube_videos` | Search YouTube |
+
+### Example Usage in Claude
+
+```
+You: Get the transcript for YouTube video dQw4w9WgXcQ
+
+Claude: [Uses get_youtube_transcript tool]
+        Here's the transcript for "Never Gonna Give You Up"...
+```
+
+---
+
+## ⚡ Rate Limiting
+
+To avoid being blocked by YouTube:
+
+```typescript
+// Add delays between requests
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+for (const videoId of videoIds) {
+  const transcript = await getTranscript(videoId);
+  await sleep(1000); // Wait 1 second between requests
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines.
+
+---
+
+## 📄 License
+
+MIT © [Aitofy](https://github.com/aitofy)
+
+---
+
+## 🙏 Credits
+
+Inspired by:
+- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api) (Python)
+- [youtubei.js](https://github.com/LuanRT/YouTube.js)