clippy-ai-agent

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

clippy-ai-agent

★ 21 Open GitHub ↗

🎬 Autonomous AI agent that transforms long-form videos into viral short-form content across YouTube Shorts, TikTok, and Instagram Reels using advanced AI analysis and automation.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[professional_readme (1).md](https://github.com/user-attachments/files/21819420/professional_readme.1.md)
# Clippy - Autonomous Video Repurposing Agent 🎬✂️

![Clippy Logo](https://img.shields.io/badge/Clippy-Video%20Repurposing-brightgreen?style=for-the-badge)
[![Python](https://img.shields.io/badge/Python-3.10+-blue?style=for-the-badge&logo=python)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://raw.githubusercontent.com/Yacineooak/clippy-ai-agent/main/LICENSE)

*Transform long-form content into viral short clips across YouTube Shorts, TikTok, and Instagram Reels with AI-powered automation.*

[Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)

</div>

---

## 🚀 Overview

Clippy is an intelligent video repurposing agent that automatically transforms long-form content into engaging short clips optimized for modern social media platforms. Using advanced AI analysis and offline processing, Clippy identifies viral moments and creates platform-specific content with subtitles, effects, and optimized formatting.

### Key Benefits
- **🎯 Maximize Reach**: Repurpose content across multiple platforms simultaneously
- **🔒 Privacy-First**: Offline AI processing with local data storage
- **💰 Cost-Effective**: Designed for free-tier deployment and local execution
- **📊 Data-Driven**: Built-in analytics to optimize your content strategy

---

## ✨ Features

### 🎥 **Video Processing**
- Automated video download and transcription
- Multi-format support with quality optimization
- Intelligent content segmentation

### 🤖 **AI-Powered Analysis**
- Offline LLM processing for privacy
- Viral moment detection and scoring
- Content optimization recommendations

</td>
<td width="50%">

### 📱 **Multi-Platform Publishing**
- YouTube Shorts automation
- TikTok direct posting
- Instagram Reels integration

### 📊 **Performance Analytics**
- Engagement tracking across platforms
- Trend analysis and optimization
- Viral potential prediction

</td>
</tr>
</table>

---

## 🏁 Quick Start

### Prerequisites

Ensure you have the following installed:

```bash
# Required software
Python 3.10+
FFmpeg
Git
```

### Installation

1. **Clone and setup the repository**
   ```bash
   git clone <repository-url>
   cd clippy
   pip install -r requirements.txt
   ```

2. **Download AI models** (automatic on first run)
   ```bash
   python -c "from src.ai.llm_analyzer import LLMAnalyzer; LLMAnalyzer({'model_name': 'orca-mini-3b-gguf2-q4_0.gguf'})"
   ```

3. **Configure your settings**
   ```bash
   cp config.yaml.example config.yaml
   # Edit config.yaml with your platform credentials
   ```

### Usage Examples

<details>
<summary><b>🎬 Single Video Processing</b></summary>

```bash
python main.py --url "https://youtube.com/watch?v=VIDEO_ID"
```
</details>

<details>
<summary><b>📚 Batch Processing</b></summary>

Create `videos.txt`:
```
https://youtube.com/watch?v=VIDEO1
https://youtube.com/watch?v=VIDEO2
https://youtube.com/watch?v=VIDEO3
```

Run batch processing:
```bash
python main.py --batch videos.txt
```
</details>

<details>
<summary><b>⏰ Scheduler Mode</b></summary>

```bash
python main.py --scheduler
```
</details>

<details>
<summary><b>📈 Analytics</b></summary>

```bash
python main.py --analytics
```
</details>

---

## ⚙️ Configuration

Configure Clippy by editing the `config.yaml` file:

<details>
<summary><b>Video Settings</b></summary>

```yaml
video:
  download_quality: "720p"
  clip_duration_min: 30
  clip_duration_max: 60
```
</details>

<details>
<summary><b>Platform Configuration</b></summary>

```yaml
platforms:
  youtube:
    enabled: true
    client_id: "your-client-id"
    client_secret: "your-client-secret"
  
  tiktok:
    enabled: true
    username: "your-username"
    password: "your-password"
  
  instagram:
    enabled: true
    username: "your-username" 
    password: "your-password"
```
</details>

<details>
<summary><b>AI Configuration</b></summary>

```yaml
ai:
  model_name: "orca-mini-3b-gguf2-q4_0.gguf"
  highlight_threshold: 0.7
```
</details>

---

## 🏗️ Architecture

<details>
<summary><b>Project Structure</b></summary>

```
clippy/
├── main.py                    # Entry point and CLI
├── config.yaml               # Configuration file
├── src/
│   ├── core/                  # Core processing modules
│   │   ├── video_processor.py      # Video download & transcription
│   │   ├── content_analyzer.py     # AI-powered content analysis
│   │   └── platform_manager.py    # Multi-platform coordination
│   ├── ai/                    # AI and machine learning
│   │   ├── llm_analyzer.py         # Offline LLM analysis
│   │   ├── engagement_tracker.py   # Performance analytics
│   │   └── optimization_engine.py  # Strategy optimization
│   ├── platforms/            # Platform-specific handlers
│   │   ├── youtube_shorts.py      # YouTube Shorts API
│   │   ├── tiktok_poster.py       # TikTok automation
│   │   └── instagram_reels.py     # Instagram Reels API
│   └── utils/                # Utilities and helpers
│       ├── config.py              # Configuration management
│       ├── file_handler.py        # File operations
│       └── scheduler.py           # Task scheduling
└── data/                     # Local data storage
    ├── videos/               # Downloaded videos
    ├── clips/               # Generated clips
    └── analytics/           # Performance data
```
</details>

---

## 🔧 Platform Setup

<details>
<summary><b>📺 YouTube Shorts Setup</b></summary>

1. **Create a Google Cloud Project**
   - Visit [Google Cloud Console](https://console.cloud.google.com/)
   - Create new project or select existing one

2. **Enable YouTube Data API v3**
   - Navigate to APIs & Services → Library
   - Search for "YouTube Data API v3" and enable it

3. **Create OAuth 2.0 Credentials**
   - Go to APIs & Services → Credentials
   - Click "Create Credentials" → "OAuth 2.0 Client IDs"
   - Configure OAuth consent screen if prompted
   - Select "Desktop application" as application type
   - Download the JSON credentials file

4. **Configure credentials**
   - Save the downloaded JSON file as `youtube_credentials.json` in your clippy folder
</details>

<details>
<summary><b>📱 TikTok Setup</b></summary>

1. Add username/password to `config.yaml`
2. First run will require manual 2FA verification
3. Session cookies will be saved for future use
</details>

<details>
<summary><b>📸 Instagram Reels Setup</b></summary>

1. Add username/password to `config.yaml`
2. Enable "Less Secure Apps" or use App Password
3. Consider using a dedicated business account
</details>

---

## 📊 Analytics & Optimization

Clippy provides comprehensive analytics to optimize your content strategy:

| Feature | Description |
|---------|-------------|
| **Performance Tracking** | Monitor engagement rates, views, and likes across all platforms |
| **Trend Analysis** | Identify best-performing content types and optimal posting times |
| **AI Optimization** | Automatically adjust content strategy based on performance data |
| **Viral Prediction** | Score clips for viral potential before posting |

---

## 🐳 Docker Deployment

<details>
<summary><b>Quick Start with Docker</b></summary>

```bash
# Build and run
docker-compose up -d

# View logs
docker-compose logs -f clippy

# Stop
docker-compose down
```
</details>

<details>
<summary><b>Production Deployment</b></summary>

```bash
# Run with database and caching
docker-compose --profile with-database --profile with-redis up -d
```
</details>

---

## 🔧 Advanced Configuration

<details>
<summary><b>Custom AI Models</b></summary>

```yaml
ai:
  model_name: "custom-model.gguf"
  model_path: "/path/to/models"
  gpu_acceleration: true
```
</details>

<details>
<summary><b>Webhook Integration</b></summary>

```yaml
webhooks:
  enabled: true
  success_url: "https://your-app.com/webhook/success"
  error_url: "https://your-app.com/webhook/error"
```
</details>

<details>
<summary><b>Advanced Scheduling</b></summary>

```yaml
scheduler:
  max_videos_per_day: 10
  posting_times:
    youtube: ["09:00", "15:00", "20:00"]
    tiktok: ["12:00", "17:00", "21:00"]
    instagram: ["10:00", "14:00", "19:00"]
```
</details>

---

## 🛠️ Development

### Development Setup

```bash
# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Code formatting
black src/
flake8 src/
```

### Adding New Platforms

1. Create new platform handler in `src/platforms/`
2. Implement required methods: `post_video()`, `get_stats()`
3. Add platform configuration to `config.yaml`
4. Register platform in `platform_manager.py`

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

---

## ⚖️ License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## ⚠️ Legal Notice

> **Important**: Please ensure compliance with platform terms of service and content rights before using this tool.

- Respect platform terms of service
- Ensure you have rights to content you're repurposing
- Use automation responsibly to avoid account restrictions
- Consider rate limiting for platform compliance

---

## 📞 Support

| Resource | Link |
|----------|------|
| 📖 **Documentation** | [./docs/](./docs/) |
| 🐛 **Issues** | [Report Issues](./issues) |
| 💬 **Discussions** | [Join Discussion](./discussions) |
| 📧 **Email** | stylebenderkh@gmail.com |

</div>

---

## 🙏 Acknowledgments

Special thanks to the amazing open-source projects that make Clippy possible:

- **OpenAI Whisper** for transcription capabilities
- **GPT4All** for offline LLM processing
- **FFmpeg** for video processing
- All the incredible open-source libraries and contributors

---

**Made with ❤️ by [Yacine Khaldi](mailto:stylebenderkh@gmail.com)**

*Empowering content creators to maximize their reach across platforms*

---

⭐ **Star this repository if you find it helpful!** ⭐

</div>

clippy-ai-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README