EchoFlow 2.0 🚀

EchoFlow is a powerful, automated, and self-hosted social media publishing engine. It allows you to automatically distribute videos across YouTube, Facebook, Instagram, and TikTok from a single local watch folder.

Facebook Reels use Meta Graph API as the primary publisher, with Page-specific manual browser fallback. YouTube, Instagram, TikTok and legacy jobs retain their Playwright uploaders. A durable local scheduler manages Page routing, due times and retries.

Start here: Facebook Pages setup, JSON formats and upgrade guide.

✨ Key Features

• Content import: Scan and review MP4/MOV + JSON pairs in Page folders; optionally enable automatic import of stable pairs. Imports are deduplicated per destination.
• Multi-Page management: Connect 10 or more Facebook Pages using OAuth or Page tokens, with encrypted token storage and folder aliases.
• Calendar and scheduler: A monthly calendar with Page filters, timezone-aware rescheduling, durable retries and manual review.
• Meta API + browser publishing: Facebook Reel upload/status reconciliation and retained Playwright sessions for the other platforms.
• Rate-aware queue: Due-time dispatch, per-Page spacing, Meta usage headers and exponential backoff.
• AI SEO Generation: Integrates with Google Gemini to automatically generate viral titles, descriptions, and tags.
• Webhook Notifications: Get real-time success or failure alerts delivered straight to your Discord or Slack.
• Stealth Mode / Local First: No central server. Jobs and encrypted Page tokens live in local SQLite; browser sessions and configuration stay on the local machine.

---

🍏 Mac OS Installation Guide

This guide is specifically tailored for Mac OS users. EchoFlow requires Python 3.10+, Node.js 18+, and FFmpeg.

1. Install Prerequisites (Homebrew)

If you don't have Homebrew installed, open your Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then, install the necessary dependencies:

brew install python node ffmpeg

2. Clone the Repository

git clone https://github.com/zabid-coder/EchoFlow.git
cd EchoFlow

3. Setup the Backend (Python)

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
cd ..

4. Setup the Frontend (React/Vite)

cd frontend
npm install
cd ..

5. Start the Application

You can start the entire application using the included Mac OS startup script:

chmod +x start.command
./start.command

(Alternatively, you can just double-click the start.command file in Finder).

The Dashboard will automatically open in your default browser at http://localhost:3000.

---

🛠️ How to Use

1. Connect Accounts: Add Facebook Pages with matching folder aliases in Accounts. Connect browser sessions for YouTube, Instagram and TikTok. Follow the Meta setup guide for tokens or OAuth.
2. Configure Settings: Go to the Settings tab to set your Gemini API Key, default platforms, and configure Anti-Spam throttling.
3. Import Content: Select a destination before dragging a video onto Dashboard, or pair each video with JSON in a Page folder and use Content → Scan → Import.
4. Schedule and review: Use Calendar for timing and job details, Scheduler for pause/auto-import controls, and Queue for progress. EchoFlow must be running for local scheduled jobs to execute.

Run the backend tests with cd backend && ./venv/bin/python -m unittest discover -s tests -v, then build the frontend with npm run build --prefix frontend from the repo root. Meta integration tests are mocked; live publishing requires your authorized Meta app and Page tokens.

📜 License

This project is proprietary and built for enterprise use.