From f3bedbd4aedcb2771a5f471d484a9d9ff56d6221 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Dec 2025 13:36:56 -0500 Subject: [PATCH] docs: improve documentation clarity and fix inconsistencies - Fix BETTER_AUTH_URL inconsistency (README used BETTER_AUTH_URL, CONTRIBUTING.md and .env.example use NEXT_PUBLIC_BETTER_AUTH_URL) - Add optional environment variables section to both README and CONTRIBUTING.md - Document Freesound, Cloudflare R2, and Modal transcription setup - Clarify which variables are required vs optional for local development - Fix typo in apps/transcription/README.md (accoumt -> account) These changes help new contributors understand the full setup process and avoid confusion about environment variables. --- .github/CONTRIBUTING.md | 24 ++++++++++++++++++++++++ README.md | 26 +++++++++++++++++++++++--- apps/transcription/README.md | 2 +- 3 files changed, 48 insertions(+), 4 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 75c4120b2..56b2c3985 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -108,10 +108,34 @@ If you're unsure whether your idea falls into the preview category, feel free to UPSTASH_REDIS_REST_URL="http://localhost:8079" UPSTASH_REDIS_REST_TOKEN="example_token" + # Marble Blog (example organization key - optional for local development) + MARBLE_WORKSPACE_KEY=cm6ytuq9x0000i803v0isidst + NEXT_PUBLIC_MARBLE_API_URL=https://api.marblecms.com + # Development NODE_ENV="development" ``` + **Optional Variables (for advanced features):** + + ```bash + # Freesound API (for audio library feature) + # Get credentials at https://freesound.org/apiv2/apply/ + FREESOUND_CLIENT_ID=... + FREESOUND_API_KEY=... + + # Cloudflare R2 (for auto-captions/transcription feature) + # Get these from Cloudflare Dashboard > R2 > Manage R2 API tokens + CLOUDFLARE_ACCOUNT_ID=your-account-id + R2_ACCESS_KEY_ID=your-access-key-id + R2_SECRET_ACCESS_KEY=your-secret-access-key + R2_BUCKET_NAME=opencut-transcription + + # Modal transcription endpoint (from modal deploy transcription.py) + # See apps/transcription/README.md for setup instructions + MODAL_TRANSCRIPTION_URL=https://your-username--opencut-transcription-transcribe-audio.modal.run + ``` + **Generate BETTER_AUTH_SECRET:** ```bash diff --git a/README.md b/README.md index 1e40f1db8..a08de1fff 100644 --- a/README.md +++ b/README.md @@ -108,20 +108,40 @@ Before you begin, ensure you have the following installed on your system: # Generate a secure secret for Better Auth BETTER_AUTH_SECRET="your-generated-secret-here" - BETTER_AUTH_URL="http://localhost:3000" + NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000" # Redis (matches docker-compose.yaml) UPSTASH_REDIS_REST_URL="http://localhost:8079" UPSTASH_REDIS_REST_TOKEN="example_token" - # Marble Blog - MARBLE_WORKSPACE_KEY=cm6ytuq9x0000i803v0isidst # example organization key + # Marble Blog (example organization key - optional for local development) + MARBLE_WORKSPACE_KEY=cm6ytuq9x0000i803v0isidst NEXT_PUBLIC_MARBLE_API_URL=https://api.marblecms.com # Development NODE_ENV="development" ``` + **Optional Variables (for advanced features):** + + ```bash + # Freesound API (for audio library feature) + # Get credentials at https://freesound.org/apiv2/apply/ + FREESOUND_CLIENT_ID=... + FREESOUND_API_KEY=... + + # Cloudflare R2 (for auto-captions/transcription feature) + # Get these from Cloudflare Dashboard > R2 > Manage R2 API tokens + CLOUDFLARE_ACCOUNT_ID=your-account-id + R2_ACCESS_KEY_ID=your-access-key-id + R2_SECRET_ACCESS_KEY=your-secret-access-key + R2_BUCKET_NAME=opencut-transcription + + # Modal transcription endpoint (from modal deploy transcription.py) + # See apps/transcription/README.md for setup instructions + MODAL_TRANSCRIPTION_URL=https://your-username--opencut-transcription-transcribe-audio.modal.run + ``` + **Generate BETTER_AUTH_SECRET:** ```bash diff --git a/apps/transcription/README.md b/apps/transcription/README.md index 07be67905..a16b57662 100644 --- a/apps/transcription/README.md +++ b/apps/transcription/README.md @@ -35,7 +35,7 @@ pip install -r requirements.txt > If you don't know what Modal is: it allows us to process the actual audio and transcribe with Whisper by providing the infra to run Python code with a lot of RAM, generally affordable. -5. Once you've got a Modal accoumt, run this: +5. Once you've got a Modal account, run this: ```bash python -m modal setup