# FeedForge 🎯
A powerful tool to customize your YouTube feed based on your content preferences. FeedForge uses AI to understand your interests, searches for relevant videos, and automatically interacts with them to train YouTube's recommendation algorithm.
## 🌟 Features
- **AI-Powered Content Discovery**: Uses OpenAI's GPT-4 to generate relevant search keywords from your content preferences
- **YouTube API Integration**: Searches for high-quality videos matching your interests
- **Automated Browser Interaction**: Uses browser automation to play videos and train YouTube's algorithm
- **Customizable Playback**: Control how long each video plays during the training process
- **Cross-Platform Support**: Works on Windows, macOS, and Linux
## 🔧 Prerequisites
Before running FeedForge, ensure you have:
1. **Python 3.9 or higher** (3.11+ recommended)
2. **Google Chrome or Firefox browser** installed
3. **OpenAI API Key** - Get one from [OpenAI Platform](https://platform.openai.com/api-keys)
4. **YouTube Data API Key** - Get one from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
## 📦 Installation
### Important Note for macOS/Linux Users
Modern Python installations (Python 3.11+ on macOS with Homebrew, Ubuntu 23.04+, Fedora 38+, etc.) use PEP 668 which prevents installing packages directly into the system Python. You have several options:
### Option 1: Using pipx (Recommended for End Users)
[pipx](https://pypa.github.io/pipx/) automatically manages a virtual environment for command-line tools:
```bash
# Install pipx first (if not already installed)
# On macOS with Homebrew:
brew install pipx
pipx ensurepath
# On Ubuntu/Debian:
sudo apt install pipx
pipx ensurepath
# On other systems:
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Then install feedforge
pipx install feedforge
```
### Option 2: Using a Virtual Environment
```bash
# Create a virtual environment
python3 -m venv feedforge-env
# Activate it
# On macOS/Linux:
source feedforge-env/bin/activate
# On Windows:
feedforge-env\Scripts\activate
# Install feedforge
pip install feedforge
# Use feedforge (make sure the virtual environment is activated)
feedforge "your interests here"
```
### Option 3: User Installation (Not Recommended)
```bash
# Install to user directory only
pip install --user feedforge
# Make sure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
source ~/.bashrc # or source ~/.zshrc
```
### Option 4: System-wide with Override (Use with Caution)
```bash
# Only use this if you understand the risks
pip install --break-system-packages feedforge
```
### Development Installation
If you want to contribute or install from source:
#### 1. Clone the Repository
```bash
git clone https://github.com/RishabhKodes/feedforge.git
cd feedforge
```
#### 2. Create Virtual Environment
```bash
python3.9 -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
```
#### 3. Install in Development Mode
```bash
pip install -e .
```
This will automatically install all required dependencies:
- langchain-openai (>=0.0.5)
- google-api-python-client (>=2.0.0)
- selenium (>=4.0.0)
- click (>=8.0.0)
- python-dotenv (>=1.0.0)
- geckodriver-autoinstaller (>=0.1.0)
- chromedriver-autoinstaller (>=0.6.0)
- openai (>=1.0.0)
## ⚙️ Configuration
Feedforge supports multiple ways to provide your API keys:
### Method 1: Environment Variables (Recommended)
```bash
export OPENAI_API_KEY="your_openai_api_key_here"
export YOUTUBE_API_KEY="your_youtube_api_key_here"
```
### Method 2: .env File
Create a `.env` file in your current directory:
```env
OPENAI_API_KEY=your_openai_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
```
### Method 3: Command Line Options
```bash
feedforge "your interests" --openai-key "your_key" --youtube-key "your_key"
```
### Method 4: Home Directory Config
Create a `.feedforge.env` file in your home directory:
```bash
echo "OPENAI_API_KEY=your_key" > ~/.feedforge.env
echo "YOUTUBE_API_KEY=your_key" >> ~/.feedforge.env
```
### Getting Your API Keys
#### OpenAI API Key:
1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)
2. Sign in or create an account
3. Click "Create new secret key"
4. Copy the key and add it to your `.env` file
#### YouTube Data API Key:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable the "YouTube Data API v3"
4. Go to "Credentials" → "Create Credentials" → "API Key"
5. Copy the key and add it to your `.env` file
## 🧪 Testing Installation
To verify that FeedForge is installed correctly, run the test script:
```bash
python test_feedforge.py
```
This will test:
- All required imports
- Environment variable handling
- CLI command availability
## 🚀 Usage
### Basic Usage
```bash
# If you've set up environment variables or .env file
feedforge "I want to see videos about people building successful side projects and sharing their journey"
# Or provide API keys directly
feedforge "your interests" --openai-key "sk-..." --youtube-key "AIza..."
```
### With Custom Duration
Control how long each video plays (default is 2 seconds):
```bash
feedforge "machine learning tutorials for beginners" --duration 5
```
### Example Commands
```bash
# Startup and entrepreneurship content
feedforge "startup founders sharing their journey and lessons learned"
# Programming tutorials
feedforge "python programming tutorials and coding best practices" --duration 3
# Creative content
feedforge "digital art tutorials and creative processes" --duration 4
# Productivity and self-improvement
feedforge "productivity tips and morning routines of successful people"
```
## 🔧 How It Works
1. **Input Processing**: FeedForge takes your content description and uses OpenAI's GPT-4 to generate relevant search keywords
2. **Video Discovery**: Uses YouTube's Data API to search for high-quality videos matching those keywords
3. **Smart Selection**: Implements round-robin selection to ensure diverse content from different keywords
4. **Browser Automation**: Opens Chrome and automatically plays each video for the specified duration
5. **Algorithm Training**: Your interactions help train YouTube's recommendation algorithm to show similar content
## 🛠️ Troubleshooting
### Common Issues
#### "externally-managed-environment" Error
This error occurs on modern Python installations (macOS with Homebrew, Ubuntu 23.04+, etc.). Solutions:
1. **Use pipx** (recommended): `pipx install feedforge`
2. **Use a virtual environment**: Create and activate a venv before installing
3. **Use --user flag**: `pip install --user feedforge` (add ~/.local/bin to PATH)
4. **Override** (not recommended): `pip install --break-system-packages feedforge`
See the Installation section above for detailed instructions.
#### "No .env file found"
Make sure you've created a `.env` file in the project root directory with your API keys.
#### "Chrome not found"
FeedForge will automatically try to find Chrome in common locations:
- **macOS**: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
- **Windows**: `C:\Program Files\Google\Chrome\Application\chrome.exe`
- **Linux**: `/usr/bin/google-chrome`
If Chrome is installed elsewhere, you may need to update the path in `src/feedforge/core.py`.
#### "Invalid API Key"
- Verify your API keys are correct in the `.env` file
- Ensure your OpenAI account has sufficient credits
- Check that YouTube Data API is enabled in Google Cloud Console
#### "No videos found"
Try using more general or different keywords in your description.
### Debug Mode
For debugging, you can run the project with Python directly:
```bash
python -m feedforge.cli "your content description here"
```
## 📁 Project Structure
```
feedforge/
├── src/
│ └── feedforge/
│ ├── __init__.py # Automatic Playwright setup
│ ├── cli.py # Command-line interface
│ └── core.py # Main functionality
├── pyproject.toml # Project configuration
├── test_feedforge.py # Installation test script
├── .env.example # Environment variables template
├── .env # API keys (you create this)
└── README.md # This file
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Test your changes: `python test_feedforge.py`
5. Ensure all tests pass: `feedforge --help`
6. Submit a pull request
### Development Setup
```bash
# Clone your fork
git clone https://github.com/RishabhKodes/feedforge.git
cd feedforge
# Create virtual environment with Python 3.9+
python3.9 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .
# Run tests
python test_feedforge.py
```
## 📄 License
This project is open source. Please check the license file for details.
## ⚠️ Disclaimer
This tool automates browser interactions with YouTube. Use responsibly and in accordance with YouTube's Terms of Service. The authors are not responsible for any violations of platform policies.
## 🆘 Support
If you encounter any issues:
1. Check the troubleshooting section above
2. Ensure all prerequisites are met
3. Verify your API keys are valid
4. Create an issue on GitHub with detailed error information
---
Happy feed customizing! 🎉
Raw data
{
"_id": null,
"home_page": null,
"name": "feedforge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "youtube, feed, automation, ai, browser, selenium, recommendations, pipx",
"author": null,
"author_email": "Rishabh Bhandari <rishabhbhandari6@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/0c/3c721397642cc45f912689fabb55da0df725b14df330fba2eb5443901fe2/feedforge-0.2.7.tar.gz",
"platform": null,
"description": "# FeedForge \ud83c\udfaf\n\nA powerful tool to customize your YouTube feed based on your content preferences. FeedForge uses AI to understand your interests, searches for relevant videos, and automatically interacts with them to train YouTube's recommendation algorithm.\n\n## \ud83c\udf1f Features\n\n- **AI-Powered Content Discovery**: Uses OpenAI's GPT-4 to generate relevant search keywords from your content preferences\n- **YouTube API Integration**: Searches for high-quality videos matching your interests\n- **Automated Browser Interaction**: Uses browser automation to play videos and train YouTube's algorithm\n- **Customizable Playback**: Control how long each video plays during the training process\n- **Cross-Platform Support**: Works on Windows, macOS, and Linux\n\n## \ud83d\udd27 Prerequisites\n\nBefore running FeedForge, ensure you have:\n\n1. **Python 3.9 or higher** (3.11+ recommended)\n2. **Google Chrome or Firefox browser** installed\n3. **OpenAI API Key** - Get one from [OpenAI Platform](https://platform.openai.com/api-keys)\n4. **YouTube Data API Key** - Get one from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)\n\n## \ud83d\udce6 Installation\n\n### Important Note for macOS/Linux Users\nModern Python installations (Python 3.11+ on macOS with Homebrew, Ubuntu 23.04+, Fedora 38+, etc.) use PEP 668 which prevents installing packages directly into the system Python. You have several options:\n\n### Option 1: Using pipx (Recommended for End Users)\n[pipx](https://pypa.github.io/pipx/) automatically manages a virtual environment for command-line tools:\n\n```bash\n# Install pipx first (if not already installed)\n# On macOS with Homebrew:\nbrew install pipx\npipx ensurepath\n\n# On Ubuntu/Debian:\nsudo apt install pipx\npipx ensurepath\n\n# On other systems:\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# Then install feedforge\npipx install feedforge\n```\n\n### Option 2: Using a Virtual Environment\n```bash\n# Create a virtual environment\npython3 -m venv feedforge-env\n\n# Activate it\n# On macOS/Linux:\nsource feedforge-env/bin/activate\n# On Windows:\nfeedforge-env\\Scripts\\activate\n\n# Install feedforge\npip install feedforge\n\n# Use feedforge (make sure the virtual environment is activated)\nfeedforge \"your interests here\"\n```\n\n### Option 3: User Installation (Not Recommended)\n```bash\n# Install to user directory only\npip install --user feedforge\n\n# Make sure ~/.local/bin is in your PATH\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc # or ~/.zshrc\nsource ~/.bashrc # or source ~/.zshrc\n```\n\n### Option 4: System-wide with Override (Use with Caution)\n```bash\n# Only use this if you understand the risks\npip install --break-system-packages feedforge\n```\n\n### Development Installation\nIf you want to contribute or install from source:\n\n#### 1. Clone the Repository\n```bash\ngit clone https://github.com/RishabhKodes/feedforge.git\ncd feedforge\n```\n\n#### 2. Create Virtual Environment\n```bash\npython3.9 -m venv venv\n# On Windows:\nvenv\\Scripts\\activate\n# On macOS/Linux:\nsource venv/bin/activate\n```\n\n#### 3. Install in Development Mode\n```bash\npip install -e .\n```\n\nThis will automatically install all required dependencies:\n- langchain-openai (>=0.0.5)\n- google-api-python-client (>=2.0.0)\n- selenium (>=4.0.0)\n- click (>=8.0.0)\n- python-dotenv (>=1.0.0)\n- geckodriver-autoinstaller (>=0.1.0)\n- chromedriver-autoinstaller (>=0.6.0)\n- openai (>=1.0.0)\n\n## \u2699\ufe0f Configuration\n\nFeedforge supports multiple ways to provide your API keys:\n\n### Method 1: Environment Variables (Recommended)\n```bash\nexport OPENAI_API_KEY=\"your_openai_api_key_here\"\nexport YOUTUBE_API_KEY=\"your_youtube_api_key_here\"\n```\n\n### Method 2: .env File\nCreate a `.env` file in your current directory:\n```env\nOPENAI_API_KEY=your_openai_api_key_here\nYOUTUBE_API_KEY=your_youtube_api_key_here\n```\n\n### Method 3: Command Line Options\n```bash\nfeedforge \"your interests\" --openai-key \"your_key\" --youtube-key \"your_key\"\n```\n\n### Method 4: Home Directory Config\nCreate a `.feedforge.env` file in your home directory:\n```bash\necho \"OPENAI_API_KEY=your_key\" > ~/.feedforge.env\necho \"YOUTUBE_API_KEY=your_key\" >> ~/.feedforge.env\n```\n\n### Getting Your API Keys\n\n#### OpenAI API Key:\n1. Visit [OpenAI Platform](https://platform.openai.com/api-keys)\n2. Sign in or create an account\n3. Click \"Create new secret key\"\n4. Copy the key and add it to your `.env` file\n\n#### YouTube Data API Key:\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select existing one\n3. Enable the \"YouTube Data API v3\"\n4. Go to \"Credentials\" \u2192 \"Create Credentials\" \u2192 \"API Key\"\n5. Copy the key and add it to your `.env` file\n\n## \ud83e\uddea Testing Installation\n\nTo verify that FeedForge is installed correctly, run the test script:\n\n```bash\npython test_feedforge.py\n```\n\nThis will test:\n- All required imports\n- Environment variable handling\n- CLI command availability\n\n## \ud83d\ude80 Usage\n\n### Basic Usage\n```bash\n# If you've set up environment variables or .env file\nfeedforge \"I want to see videos about people building successful side projects and sharing their journey\"\n\n# Or provide API keys directly\nfeedforge \"your interests\" --openai-key \"sk-...\" --youtube-key \"AIza...\"\n```\n\n### With Custom Duration\nControl how long each video plays (default is 2 seconds):\n```bash\nfeedforge \"machine learning tutorials for beginners\" --duration 5\n```\n\n### Example Commands\n```bash\n# Startup and entrepreneurship content\nfeedforge \"startup founders sharing their journey and lessons learned\"\n\n# Programming tutorials\nfeedforge \"python programming tutorials and coding best practices\" --duration 3\n\n# Creative content\nfeedforge \"digital art tutorials and creative processes\" --duration 4\n\n# Productivity and self-improvement\nfeedforge \"productivity tips and morning routines of successful people\"\n```\n\n## \ud83d\udd27 How It Works\n\n1. **Input Processing**: FeedForge takes your content description and uses OpenAI's GPT-4 to generate relevant search keywords\n2. **Video Discovery**: Uses YouTube's Data API to search for high-quality videos matching those keywords\n3. **Smart Selection**: Implements round-robin selection to ensure diverse content from different keywords\n4. **Browser Automation**: Opens Chrome and automatically plays each video for the specified duration\n5. **Algorithm Training**: Your interactions help train YouTube's recommendation algorithm to show similar content\n\n## \ud83d\udee0\ufe0f Troubleshooting\n\n### Common Issues\n\n#### \"externally-managed-environment\" Error\nThis error occurs on modern Python installations (macOS with Homebrew, Ubuntu 23.04+, etc.). Solutions:\n1. **Use pipx** (recommended): `pipx install feedforge`\n2. **Use a virtual environment**: Create and activate a venv before installing\n3. **Use --user flag**: `pip install --user feedforge` (add ~/.local/bin to PATH)\n4. **Override** (not recommended): `pip install --break-system-packages feedforge`\n\nSee the Installation section above for detailed instructions.\n\n#### \"No .env file found\"\nMake sure you've created a `.env` file in the project root directory with your API keys.\n\n#### \"Chrome not found\"\nFeedForge will automatically try to find Chrome in common locations:\n- **macOS**: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`\n- **Windows**: `C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe`\n- **Linux**: `/usr/bin/google-chrome`\n\nIf Chrome is installed elsewhere, you may need to update the path in `src/feedforge/core.py`.\n\n#### \"Invalid API Key\"\n- Verify your API keys are correct in the `.env` file\n- Ensure your OpenAI account has sufficient credits\n- Check that YouTube Data API is enabled in Google Cloud Console\n\n#### \"No videos found\"\nTry using more general or different keywords in your description.\n\n### Debug Mode\nFor debugging, you can run the project with Python directly:\n```bash\npython -m feedforge.cli \"your content description here\"\n```\n\n## \ud83d\udcc1 Project Structure\n\n```\nfeedforge/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 feedforge/\n\u2502 \u251c\u2500\u2500 __init__.py # Automatic Playwright setup\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 core.py # Main functionality\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 test_feedforge.py # Installation test script\n\u251c\u2500\u2500 .env.example # Environment variables template\n\u251c\u2500\u2500 .env # API keys (you create this)\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Test your changes: `python test_feedforge.py`\n5. Ensure all tests pass: `feedforge --help`\n6. Submit a pull request\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/RishabhKodes/feedforge.git\ncd feedforge\n\n# Create virtual environment with Python 3.9+\npython3.9 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .\n\n# Run tests\npython test_feedforge.py\n```\n\n## \ud83d\udcc4 License\n\nThis project is open source. Please check the license file for details.\n\n## \u26a0\ufe0f Disclaimer\n\nThis tool automates browser interactions with YouTube. Use responsibly and in accordance with YouTube's Terms of Service. The authors are not responsible for any violations of platform policies.\n\n## \ud83c\udd98 Support\n\nIf you encounter any issues:\n1. Check the troubleshooting section above\n2. Ensure all prerequisites are met\n3. Verify your API keys are valid\n4. Create an issue on GitHub with detailed error information\n\n---\n\nHappy feed customizing! \ud83c\udf89\n",
"bugtrack_url": null,
"license": null,
"summary": "A powerful AI-driven tool to customize your YouTube feed based on your content preferences using browser automation",
"version": "0.2.7",
"project_urls": {
"Bug Tracker": "https://github.com/RishabhKodes/feedforge/issues",
"Documentation": "https://github.com/RishabhKodes/feedforge#readme",
"Homepage": "https://github.com/RishabhKodes/feedforge",
"Repository": "https://github.com/RishabhKodes/feedforge"
},
"split_keywords": [
"youtube",
" feed",
" automation",
" ai",
" browser",
" selenium",
" recommendations",
" pipx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8590823ab6df507fb3e7b645bbdf3354bfb12692b8bf3991070bc3085fd3df92",
"md5": "1253dd3e8a297db8241eca244d1b5763",
"sha256": "c3ebfb2dfd7dc712165f83d4ba26c161d9dfe5595121cde8c0dd9cefed5f9298"
},
"downloads": -1,
"filename": "feedforge-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1253dd3e8a297db8241eca244d1b5763",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 15295,
"upload_time": "2025-09-01T15:40:46",
"upload_time_iso_8601": "2025-09-01T15:40:46.474444Z",
"url": "https://files.pythonhosted.org/packages/85/90/823ab6df507fb3e7b645bbdf3354bfb12692b8bf3991070bc3085fd3df92/feedforge-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a20c3c721397642cc45f912689fabb55da0df725b14df330fba2eb5443901fe2",
"md5": "79081bd76db85cab8ad9b55ed91f5b42",
"sha256": "8095c3f239faadb37a2e515741c5487ee58718ea10a49d53a330be6db0099935"
},
"downloads": -1,
"filename": "feedforge-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "79081bd76db85cab8ad9b55ed91f5b42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17871,
"upload_time": "2025-09-01T15:40:47",
"upload_time_iso_8601": "2025-09-01T15:40:47.707617Z",
"url": "https://files.pythonhosted.org/packages/a2/0c/3c721397642cc45f912689fabb55da0df725b14df330fba2eb5443901fe2/feedforge-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 15:40:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RishabhKodes",
"github_project": "feedforge",
"github_not_found": true,
"lcname": "feedforge"
}
JSON
