Skip to content
Projects

pickeld/pick-a-recipe has 57 GitHub stars and 9 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-15 21:09 UTC. Last push 2026-11-08.

How these counts are measured

57 stars9 Forks +1 in 24h

What you can do

  • 🎥 Multi-platform video support (TikTok, YouTube, Instagram, etc.)
  • 🎙️ Audio transcription with language detection
  • 👁️ Visual text extraction from video frames
  • 🤖 AI-powered recipe generation with structured ingredients

Measured star growth

in 24h
+1
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Pick-a-Recipe: AI-powered recipe extraction from TikTok, YouTube & Instagram videos with automatic import to Tandoor/Mealie recipe managers.

AI

README.md

Original

Pick-a-Recipe

Pick-a-Recipe

Python Docker Hub Docker Pulls Flask License

Extract recipes from social media videos (TikTok, YouTube, Instagram, etc.) and automatically import them into your self-hosted recipe manager.

Overview

Pick-a-Recipe is a Python application that:

  1. Downloads videos from TikTok, YouTube, Instagram, and other platforms using yt-dlp
  2. Transcribes audio using Whisper AI (via faster-whisper)
  3. Extracts on-screen text (ingredients, instructions) using vision-capable LLMs
  4. Generates structured recipes using an AI provider you configure (OpenAI, Google Gemini, Anthropic, or any OpenAI-compatible endpoint)
  5. Uploads to recipe managers - supports Tandoor and Mealie

Features

  • 🎥 Multi-platform video support (TikTok, YouTube, Instagram, etc.)
  • 🎙️ Audio transcription with language detection
  • 👁️ Visual text extraction from video frames
  • 🤖 AI-powered recipe generation with structured ingredients
  • 🍽️ Automatic nutrition and serving size estimation, backed by Open Food Facts
  • 🖼️ Dish image extraction with manual selection option
  • 🌐 Web UI with real-time progress updates
  • 🔐 User authentication and settings management
  • 🐳 Docker support for easy deployment
  • 📱 PWA Support - Install as app on mobile, share URLs directly from Android/iOS

Requirements

  • Python 3.11+
  • FFmpeg (for video/audio processing)
  • An API key for OpenAI, Google Gemini or Anthropic — or any OpenAI-compatible endpoint (OpenRouter, Groq, a local Ollama, …)
  • Self-hosted Tandoor or Mealie instance (optional)

Installation

Using Docker (Recommended)

Option 1: Pull from Docker Hub (Easiest)

docker run -d \
  --name pick-a-recipe \
  -p 5006:5006 \
  -e FLASK_SECRET_KEY="your-secure-secret-key" \
  -e LOG_LEVEL=info \
  -v pick-a-recipe-data:/app/data \
  pickeld/pick-a-recipe:latest

Open http://localhost:5006 and pick a username and password. That first visit is the only time the setup page is available; once an account exists it closes for good.

No identity provider is needed. If you would rather sign in through single sign-on, see Authentication.

Option 2: Using Docker Compose

Create a docker-compose.yml file:

version: "3.8"

services:
  pick-a-recipe:
    image: pickeld/pick-a-recipe:latest
    container_name: pick-a-recipe
    restart: unless-stopped
    ports:
      - "5006:5006"
    environment:
      - FLASK_SECRET_KEY=your-secure-secret-key
      # info by default. debug when a bug report needs every step; restart after changing it.
      - LOG_LEVEL=info
    volumes:
      - pick-a-recipe-data:/app/data

volumes:
  pick-a-recipe-data:

Then run:

docker-compose up -d

Open http://localhost:5006 and create your account.

Manual Installation

  1. Clone the repository:

    git clone https://github.com/pickeld/pick-a-recipe.git
    cd pick-a-recipe
    
  2. Install system dependencies:

    # macOS
    brew install ffmpeg
    
    # Ubuntu/Debian
    sudo apt-get install ffmpeg
    
  3. Create a virtual environment and install Python dependencies:

    python3 -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    
  4. Run the application:

    python ui/app.py
    
  5. Open http://localhost:5006 and create your account on the setup page.

Configuration

All configuration is managed through the web UI settings page (/settings).

Authentication

Sign-in is always required. Settings holds your LLM, Mealie and Tandoor API keys, so an instance anyone can reach is an instance that hands those out.

Two modes, selected with AUTH_MODE:

AUTH_MODE Behaviour
local (default) Username and password accounts stored by this app. No identity provider needed.
oidc Single sign-on through any OpenID Connect provider — Authentik, Authelia, Keycloak, Pocket ID, Zitadel, Okta … Accounts and groups come from that provider.

local — accounts stored by this app (default)

Start the app and open it in a browser. With no account yet, every page redirects to /setup, where you choose a username and password:

docker run -d --name pick-a-recipe -p 5006:5006 \
  -v pick-a-recipe-data:/app/data \
  pickeld/pick-a-recipe:latest

The setup page is reachable only while the instance has no account, and closes permanently once one exists — so nobody can use it to add a second admin or reset your password. If your instance is already reachable from the internet when you first start it, create the account promptly: until you do, whoever loads that page first gets it. AUTH_LOCAL_USERNAME prefills the username field, nothing more.

Passwords must be at least 10 characters, with no composition rules: length is what makes a password hard to guess, while forced symbols mostly produce predictable substitutions. They are stored as Argon2id hashes with a per-account salt, and rehashed automatically if the cost parameters are ever raised.

Repeated failures are slowed progressively rather than locking the account, which would let anyone who knows your username lock you out at will. Wrong password and no-such-user return the same message and take comparable time, so the login form cannot be used to discover which accounts exist.

Accounts and admins

The account created on the setup page is an admin. Admins see the whole settings page and manage accounts there; everyone else gets a sign-in and a password form. That split exists because settings holds your API keys, so an ordinary account should not be able to read them.

Admins can add accounts, grant or revoke admin rights, set a password for someone who forgot theirs, and delete accounts. There is no self-registration: on a self-hosted instance, an open sign-up form is a way in for anyone who finds the URL. Two rules cannot be worked around, because either would leave the instance with no way back in: you cannot remove your own admin rights, and you cannot remove the last admin's.

Deleting an account removes its queued and in-progress jobs and its pending uploads. Recipes that finished are left alone — they belong to the instance, and the person leaving is usually not the only one who cares about them. Deleting or demoting someone takes effect on their next request rather than whenever their cookie expires, so revoking access is immediate.

Changing your own password requires your current one, so a borrowed session cannot be used to lock you out of your own account.

In oidc mode this section does not apply: accounts, passwords and group membership live in the identity provider, and the settings page says so instead of offering controls that could not work.

Upgrading from AUTH_MODE=none

That mode is gone; authentication can no longer be switched off. An instance still setting it boots with a warning and is treated as local, landing on the setup page. Ownership of recipes and history is recorded against the username that mode used, so the setup page offers that name and reuses the account rather than creating a second one — accept it, pick a password, and your history carries over. Typing a different name starts with an empty history. Update your configuration to AUTH_MODE=local, or drop the variable entirely.

oidc — single sign-on

Works with any OpenID Connect provider: Authentik, Authelia, Keycloak, Pocket ID, Zitadel, Okta and the rest. Nothing here is specific to one of them — the app only uses OIDC discovery, the authorization code flow and standard claims.

Register a confidential OAuth2/OIDC client for the app with the redirect URI https://your-host/auth/callback, then set:

AUTH_MODE=oidc
OIDC_ISSUER_URL=https://auth.example.com/application/o/pick-a-recipe
OIDC_CLIENT_ID=...
OIDC_CLIENT_SECRET=...
OIDC_PROVIDER_NAME=Authentik   # optional, names the sign-in button

OIDC_ISSUER_URL is the URL whose /.well-known/openid-configuration describes the provider. Everything else is discovered from there.

Access is gated on group membership: users need OIDC_USER_GROUP (default pick-a-recipe-users), and admins additionally need OIDC_ADMIN_GROUP (default admins). Set OIDC_USER_GROUP= (empty) to let every authenticated user in, which is what you want from a provider that does not publish groups.

Groups are read from the claim named by OIDC_GROUPS_CLAIM (default groups), accepting a list of names, a space- or comma-separated string, or a list of objects with name/path. Keycloak's leading / on path-style groups is ignored, so configure the plain name. Publishing that claim is provider-specific: Authentik needs the authentik read groups scope mapping on the provider, Keycloak a group membership mapper, Authelia the groups scope.

Behind a reverse proxy, set PUBLIC_URL (or OIDC_REDIRECT_URI) so the OIDC callback URL matches what you registered with the provider, and set SESSION_COOKIE_SECURE=true when serving over HTTPS.

Password sign-in is refused outright in this mode, so an account that happens to carry a password cannot be used to go around single sign-on.

With AUTH_MODE=oidc set but no issuer or client credentials configured, nobody can sign in and the login page says so. It fails closed on purpose; drop AUTH_MODE to fall back to local accounts.

Upgrading: AUTH_MODE=authentik and the AUTHENTIK_* variables still work — they map onto oidc and the matching OIDC_* names, with a note in the log. Nothing needs changing to keep an existing Authentik setup running.

Android app sign-in

The Android app in mobile/ authenticates with bearer tokens. Set a signing key to enable it:

JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")

With JWT_SECRET_KEY unset the whole mobile surface stays disabled and those endpoints return 503.

The app asks for your server's address on first launch — nothing is compiled in, since everyone runs their own instance — then reads /api/auth/status and offers whichever sign-in that instance has. Under local it posts the username and password to /api/mobile/auth/login, which applies the same throttle ladder as the web form, so neither is a way around the other. Under oidc a password is refused there: group membership governs access, not any password an account happens to carry.

For single sign-on the app cannot hold the OIDC client secret, so it opens the system browser, the server completes the code exchange, and the resulting token pair is handed back over a custom-scheme deep link (par://auth/callback by default, configurable with MOBILE_DEEP_LINK_SCHEMES). Tokens travel in the URL fragment, which browsers do not send to servers or leak via Referer.

Access tokens last 15 minutes and refresh tokens 30 days; POST /api/mobile/auth/refresh re-reads the account on every refresh, so removing someone from the authorized group — or deleting or demoting a local account — takes effect within the access-token lifetime rather than lasting for the life of the refresh token.

Bearer tokens are accepted on the existing API endpoints alongside cookie sessions; cookies take precedence when both are present.

Settings

Setting Description
AI Providers The models this instance can reach — see AI providers
AI Extraction Which provider turns video and page content into a recipe
Speech to Text Whisper on this server, or a provider with an audio endpoint
Recipe Language Target language for recipe output (e.g., hebrew, english)
Target Language Code ISO language code for transcription (e.g., he, en)
Whisper Model Whisper model size (tiny, small, medium, large)
Output Target Recipe manager: tandoor or mealie
Tandoor Host URL of your Tandoor instance
Tandoor API Key API token from Tandoor
Mealie Host URL of your Mealie instance
Mealie API Key API token from Mealie
Confirm Before Upload Show recipe preview before uploading
Nutrition lookup Look ingredients the built-in table does not know up in Open Food Facts (on by default; no API key needed)

Nutrition

Per-serving nutrition is worked out from the ingredient list, not guessed by the model. Each ingredient is converted to grams and costed against a built-in table of per-100 g figures covering the ~180 foods that come up most often, in English and Hebrew.

Anything the table does not recognise is looked up in Open Food Facts — an open, collaborative food database with worldwide coverage, which needs no API key or account. Because its entries are individual branded products, the median of several popular matches is used rather than the first hit. Results are cached, outbound searches are capped at ten a minute to stay within what Open Food Facts asks of clients, and a failed lookup is simply skipped: nutrition is an extra, and never fails an extraction.

Turn Nutrition lookup off in Settings for a fully offline instance. The built-in table keeps working either way.

Open Food Facts data is published under the Open Database License.

AI providers

Nothing is hardcoded to a vendor. Under Settings -> AI Providers you add as many providers as you like, each one a name plus four things:

Field What it is
API type The dialect the endpoint speaks: OpenAI (Responses API), OpenAI-compatible (Chat Completions), Google Gemini, or Anthropic (Claude)
API key The provider's key. A local server (Ollama, LM Studio, vLLM) needs none
Model Free text, always. Suggestions come from models.dev, but a model it has never heard of works just the same
Base URL Only for OpenAI-compatible endpoints — https://openrouter.ai/api/v1, https://api.groq.com/openai/v1, http://localhost:11434/v1, whatever you run

So OpenRouter is no longer a special case in the code: it is one OpenAI-compatible endpoint among many, distinguished only by its base URL. The same field reaches Groq, Together, DeepSeek, Mistral, xAI, LiteLLM, a self-hosted vLLM or an Ollama on your LAN.

The sections below then choose from those providers rather than carrying keys of their own:

  • AI Extraction turns video and page content into a structured recipe. It also reads on-screen text and picks the dish photo, so it needs a model that can see images.
  • Speech to Text either runs Whisper on this server — no API, no network — or posts the audio to a provider with an OpenAI-compatible /audio/transcriptions endpoint. A provider that fails falls back to local Whisper rather than losing the audio.

The HuggingFace token under Speech to Text is not an AI provider key: it only makes the Whisper weights download faster and at a higher rate limit.

If a model is retired, the app fails over to the next known-good model for that dialect and writes the working one back to that provider. OpenAI-compatible providers have no such chain — a model name that works on Groq is a 404 on OpenRouter — so there you get a clear error naming the provider instead.

Upgrading: an existing install keeps working untouched. The old llm_provider, openai_*, gemini_* and openrouter_* settings are read as a provider registry on first load, with the provider you had selected still selected.

Usage

Web UI

  1. Navigate to http://localhost:5006
  2. Log in with your credentials
  3. Paste a video URL (TikTok, YouTube, Instagram, etc.)
  4. Click "Extract Recipe"
  5. Watch the real-time progress as the video is processed
  6. If "Confirm Before Upload" is enabled, review and optionally edit the recipe
  7. The recipe is automatically uploaded to your configured recipe manager

PWA / Mobile App (Share Links Directly)

Pick-a-Recipe supports PWA (Progressive Web App) installation, allowing you to share video links directly from your phone:

Android

  1. Open https://your-server:5006 in Chrome
  2. Tap the menu (⋮) → "Add to Home screen"
  3. Now when sharing any video link, choose "Pick-a-Recipe" from the share sheet

iPhone / iPad

  1. Open https://your-server:5006 in Safari
  2. Tap the Share button → "Add to Home Screen"
  3. Open the app from your home screen
  4. Share video links from TikTok/Instagram/YouTube using the Share button → "Pick-a-Recipe"

Note: PWA features require HTTPS in production. For local testing, localhost works without HTTPS.

Command Line

For testing or batch processing, you can use the CLI:

# Basic usage
python main.py "https://www.tiktok.com/@user/video/1234567890"

# Skip upload (just generate recipe JSON)
python main.py --no-upload "https://www.youtube.com/watch?v=VIDEO_ID"

Project Structure

pick-a-recipe/
├── main.py              # CLI entry point
├── chef.py              # AI recipe generation
├── config.py            # Configuration management
├── video_downloader.py  # Video downloading (yt-dlp)
├── transcriber.py       # Audio transcription (Whisper)
├── image_extractor.py   # Dish image extraction
├── mealie.py            # Mealie API integration
├── tandoor.py           # Tandoor API integration
├── recipe_exporter.py   # Recipe export utilities
├── helpers.py           # Utility functions and prompts
├── ai_providers.py      # Configurable AI providers + one client per dialect
├── frame_selector.py    # Picks the dish photo via the configured provider
├── model_catalog.py     # Model suggestions with prices (models.dev, OpenRouter live) for the settings page
├── ui/                  # Flask web UI
│   ├── app.py           # Flask application
│   ├── database.py      # SQLite database management
│   ├── templates/       # HTML templates
│   └── static/          # CSS and JavaScript
├── Dockerfile
├── docker-compose.yml
├── docker-compose.srv2.yml   # srv2 reference (see portainer/ for production)
├── build-and-push.sh         # Publish pickeld/pick-a-recipe to Docker Hub
├── portainer/
│   ├── stack.yml             # Portainer / srv2 production stack
│   └── stack.env             # Stack env template (copy to stack.env.local)
├── scripts/
│   ├── portainer-migrate.sh  # srv2 deploy: pull image + restart stack
│   └── portainer-deploy.sh   # Deploy via Portainer API
└── requirements.txt

Docker Deployment

Docker Hub Image

The official image is available on Docker Hub: pickeld/pick-a-recipe

# Pull the latest image
docker pull pickeld/pick-a-recipe:latest

# Or pin an exact build: every push to main is also tagged with its commit SHA
docker pull pickeld/pick-a-recipe:<commit-sha>

Published for linux/amd64 and linux/arm64, so the same tag works on Intel/AMD machines, a Raspberry Pi 4 or 5 running a 64-bit OS, Apple Silicon and ARM cloud servers. 32-bit ARM (linux/arm/v7, e.g. 32-bit Raspberry Pi OS) is not supported: faster-whisper's CTranslate2 backend and deno ship no builds for it.

Environment Variables

Variable Description Default
HOST Host to bind to 0.0.0.0
PORT Port to listen on 5006
FLASK_SECRET_KEY Secret key for session cookies Auto-generated
FLASK_DEBUG Enable debug mode false
MAX_CONCURRENT_JOBS Parallel extraction workers (1–16) 3 (or Settings value)
AUTH_MODE local for accounts stored by this app, or oidc for SSO (details) local
AUTH_LOCAL_USERNAME Prefills the username field on the setup page admin
OIDC_ISSUER_URL OIDC issuer URL, the one serving /.well-known/openid-configuration (required when AUTH_MODE=oidc) —
OIDC_CLIENT_ID OAuth2 client ID (required when AUTH_MODE=oidc) —
OIDC_CLIENT_SECRET OAuth2 client secret (required when AUTH_MODE=oidc) —
OIDC_USER_GROUP Group required for access; empty admits any authenticated user pick-a-recipe-users
OIDC_ADMIN_GROUP Group granting admin rights admins
OIDC_GROUPS_CLAIM Claim the group names are read from groups
OIDC_SCOPES Scopes requested at the provider openid email profile groups
OIDC_PROVIDER_NAME Name shown on the sign-in button SSO
OIDC_REDIRECT_URI Callback URL, when PUBLIC_URL is not enough derived
AUTHENTIK_* Deprecated aliases for the OIDC_* variables above —
JWT_SECRET_KEY Signing key for Android app tokens; unset disables mobile auth —
MOBILE_DEEP_LINK_SCHEMES Comma-separated URL schemes the app may receive tokens on par
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY Web Push signing pair (details) Generated on first use
VAPID_SUBJECT Contact URI push services can use to reach you mailto:[email protected]
SESSION_COOKIE_SECURE Set secure cookie flag (use with HTTPS) false

Notifications

Extraction takes minutes, so the useful signal — your recipe is saved, it failed, or it is waiting on you — lands after you have already closed the tab. Turn on Settings → Notifications in each browser you want notified, and the app pushes that signal to the OS.

Approvals are the ones worth enabling: they expire, and a missed one discards the extraction. That notification carries the deadline and is not delivered after the window closes.

Requires HTTPS (or localhost) — browsers refuse push on plain HTTP. On iOS, add the app to the Home Screen first; Safari only allows push for installed PWAs.

Nothing to configure: the server mints a VAPID key pair on first use and stores it in the database. Set VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY to manage the pair yourself instead — they take precedence when both are set. Generate one with:

python -c "
import base64
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
k = ec.generate_private_key(ec.SECP256R1())
b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b'=').decode()
print('VAPID_PUBLIC_KEY=' + b64(k.public_key().public_bytes(
    serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint)))
print('VAPID_PRIVATE_KEY=' + b64(
    k.private_numbers().private_value.to_bytes(32, 'big')))
"

Changing the pair invalidates every existing subscription — each browser has to re-enable notifications — so keep it out of source control and treat it like any other credential.

Docker Compose (Using Docker Hub)

version: "3.8"

services:
  pick-a-recipe:
    image: pickeld/pick-a-recipe:latest
    container_name: pick-a-recipe
    restart: unless-stopped
    ports:
      - "5006:5006"
    environment:
      - HOST=0.0.0.0
      - PORT=5006
      - FLASK_SECRET_KEY=your-secure-secret-key
      # Local accounts by default; create yours on first visit at /setup
    volumes:
      - pick-a-recipe-data:/app/data

volumes:
  pick-a-recipe-data:

Building and Publishing to Docker Hub

CI publishes the multi-arch image (linux/amd64, linux/arm64) on every push to main — see .github/workflows/deploy.yml — and will not move :latest unless both architectures built. To push one by hand:

docker logout && docker login -u pickeld   # or [email protected]
./build-and-push.sh latest

Published as pickeld/pick-a-recipe on Docker Hub.

srv2 / Portainer deployment

Production on srv2 is managed by Portainer. Add credentials to portainer/stack.env.local, then deploy:

cd /opt/pick-a-recipe
cp portainer/stack.env portainer/stack.env.local
# Edit stack.env.local: FLASK_SECRET_KEY, PORTAINER_URL, PORTAINER_USER, PORTAINER_PASSWORD

./scripts/portainer-migrate.sh

Or deploy/update directly:

./scripts/portainer-deploy.sh --pull --force-recreate

Important: Do not use docker compose up directly — Portainer will show "created outside of Portainer" and limit control. Always deploy via the scripts above or the Portainer UI.

Note: Existing srv2 installs may still use the legacy Docker volume social_recipe_social-recipes for data; the stack preserves it automatically.

Building from Source

If you prefer to build the image yourself:

git clone https://github.com/pickeld/pick-a-recipe.git
cd pick-a-recipe
docker build -t pick-a-recipe .
docker run -p 5006:5006 -e FLASK_SECRET_KEY="your-secret" pick-a-recipe

Supported Platforms

Pick-a-Recipe uses yt-dlp for video downloading, which supports:

  • TikTok
  • YouTube
  • Instagram Reels
  • Facebook Videos
  • Twitter/X Videos
  • And many more

Instagram troubleshooting

Instagram frequently blocks automated downloads. Pick-a-Recipe installs yt-dlp[curl-cffi] for browser impersonation, which is required for most public reels.

If you still see "Instagram sent an empty media response":

  1. Update to the latest Docker image or reinstall: pip install "yt-dlp[curl-cffi]"
  2. Confirm the reel opens in a private/incognito browser window (not logged in). If it does not, the post is private — upload a cookies.txt in Settings while logged into Instagram.
  3. Upload cookies in Settings → Video Downloads (export from your browser while logged into instagram.com).

This is an upstream Instagram/yt-dlp limitation, not a bug in the recipe extraction itself. See yt-dlp issue #17074 for background.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.