YTNotes

YTNotes is a FastAPI app for turning YouTube videos into structured notes with folders, subscriptions, and AI-powered features.

What you need

Before starting the app, make sure these services are available:

• Python 3.13
• PostgreSQL
• Redis
• Google OAuth credentials
• Optional: ngrok for OAuth callback and Paddle webhook testing
• Optional: OpenAI API key for chat and note generation
• Optional: SmartProxy credentials for YouTube transcript extraction
• Optional: Paddle sandbox credentials for subscription testing

Start the project after cloning

1. Clone the repository and enter it.

   git clone <your-github-repo-url>
   cd ytnotes

2. Install the Python dependencies.

   uv sync

3. Start PostgreSQL and Redis locally.

   Make sure PostgreSQL is running and the database named ytnotes exists. Also start Redis on localhost:6379.

4. Configure your environment variables.

   Update .env or .env.local with your local values. At minimum, you need:

   • DATABASE_URL
   • SECRET
   • JWT_SECRET
   • JWT_ALGO
   • ACCESS_TTL_MIN
   • REFRESH_TTL_MIN
   • GOOGLE_CLIENT_ID
   • GOOGLE_CLIENT_SECRET
   • OPENAI_API_KEY
   • SMART_PROXY_USERNAME
   • SMART_PROXY_PASSWORD
   • SUBSCRIPTION_GUARD_ENABLED (set false while developing)
   • PADDLE_ENV (sandbox or production)
   • PADDLE_API_KEY
   • PADDLE_WEBHOOK_SECRET
   • PADDLE_CLIENT_TOKEN
   • PADDLE_MONTHLY_PRICE_ID
   • PADDLE_YEARLY_PRICE_ID
   • PADDLE_MONTHLY_AMOUNT (in cents, e.g. 1900)
   • PADDLE_YEARLY_AMOUNT (in cents, e.g. 19900)
   • PADDLE_CURRENCY (e.g. USD)

   If you are testing through ngrok, set BASE_URL to the ngrok HTTPS URL.

5. Run database migrations.

   uv run alembic upgrade head

6. Start the application.

   uv run fastapi dev main.py

   If you prefer Uvicorn directly, this also works:

   uv run uvicorn main:app --reload

7. Open the app in your browser.

   By default the app runs at http://127.0.0.1:8000.

Optional services for full feature testing

• Google OAuth: required for login.
• ngrok: required if your Google OAuth redirect URL or Paddle webhook needs a public HTTPS endpoint.
• Paddle sandbox: required if you want to test subscription purchase or cancellation flows.
• OpenAI API: required for AI note generation and chat.
• SmartProxy: required for YouTube transcript extraction when direct transcript access is blocked.

Notes

• The app uses Redis to store and revoke auth tokens.
• The app uses Alembic for database migrations.
• If you change BASE_URL, make sure the OAuth redirect URI matches ${BASE_URL}/auth/callback.