workflows/n8n/README.md

# n8n Workflows

## Docker Compose n8n

The project Docker Compose stack includes n8n at:

```text
http://localhost:5678
```

Copy `.env.example` to `.env`, then set at least:

```env
MAESTER_API_KEY=your_maester_api_key
N8N_ENCRYPTION_KEY=generate_a_long_stable_random_value
PEXELS_API_KEY=your_pexels_api_key
```

The compose file injects these values into n8n:

```env
MAESTER_BASE_URL=http://maester-enterprise:7860
MAESTER_API_KEY=your_maester_api_key
OPENAI_API_KEY=your_openai_api_key
GEMINI_API_KEY=your_gemini_api_key
OPENROUTER_API_KEY=your_openrouter_api_key
AI_PROVIDER=openai
LLM_PROVIDER=openai
PEXELS_API_KEY=your_pexels_api_key
LLM_MODEL=gpt-4o-mini
KTTS_MODEL=kokoro-v0_19.onnx
KTTS_VOICE=af_bella.pt
```

Import any workflow JSON from this folder into n8n after the stack is running.

## AI Provider Smoke Test

Import:

```text
ai_provider_smoke_test.json
```

Set `AI_PROVIDER` or `LLM_PROVIDER` in `.env` to one of:

```text
openai
gemini
openrouter
```

The workflow uses these provider-specific variables:

```env
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-1.5-flash

OPENROUTER_API_KEY=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_SITE_URL=http://localhost:5678
OPENROUTER_APP_NAME=Maester Enterprise
```

OpenRouter uses the OpenAI-compatible chat completions format. Gemini uses the `generateContent` endpoint and returns a Gemini-shaped response.

## Webhook TikTok Storytelling With Pexels

Import:

```text
webhook_tiktok_storytelling_pexels.json
```

This workflow exposes an n8n webhook at:

```text
POST /webhook/maester/create-tiktok-story
```

Example payload:

```json
{
  "topic": "a founder saves 10 hours a week with automation",
  "series_title": "Automation Proof",
  "audience": "small business owners",
  "scene_count": 5,
  "scene_duration": 5,
  "output_name": "automation_proof_episode_01.mp4"
}
```

The webhook creates a TikTok render payload, searches Pexels for portrait clips, submits the job to `/services/render/render`, and returns Maester's `job_id`, `status_url`, and `download_url`. Poll `MAESTER_BASE_URL + status_url` until the job state is complete, then download from `MAESTER_BASE_URL + download_url`.

## TikTok Storytelling Mini Series With Pexels

Import `tiktok_storytelling_pexels.json` into n8n.

For the full autonomous version from the project specification, import:

```text
autonomous_tiktok_storytelling_miniseries.json
```

Required n8n environment variables:

```env
MAESTER_BASE_URL=https://your-maester-space.hf.space
MAESTER_API_KEY=your_maester_api_key
PEXELS_API_KEY=your_pexels_api_key
OPENAI_API_KEY=your_openai_api_key
LLM_MODEL=gpt-4o-mini
KTTS_MODEL=kokoro-v0_19.onnx
KTTS_VOICE=af_bella.pt
```

What the workflow does:

1. Builds a five-scene TikTok storytelling episode.
2. Searches Pexels videos for each scene query.
3. Picks portrait MP4 assets when available.
4. Creates a Maester render payload with scene captions, text overlays, blur background, and per-scene effects.
5. Submits the render job to `/services/render/render`.

The workflow expects all services to be enabled in Maester:

```env
MAESTER_MOUNT_SERVICES=true
MAESTER_ENABLE_RENDER_ENGINE=true
```

The final node returns the render job response. Add a `Wait` node and an HTTP Request node against the returned `status_url` if you want automatic polling.

Pexels attribution metadata is included in each scene under `metadata.pexels` so you can preserve attribution data in downstream reports.

## Autonomous Mini-Series Workflow

`autonomous_tiktok_storytelling_miniseries.json` implements this production pipeline:

1. Configures the topic: `The Girl Who Disappeared Every Midnight`.
2. Calls OpenAI Chat Completions and requests strict JSON story output.
3. Validates the returned story schema.
4. Creates a Maester campaign record through `/automation/campaigns`.
5. Runs Maester quality and compliance checks.
6. Loops through scenes inside an n8n Code node.
7. Searches Pexels portrait videos with retry queries.
8. Generates KTTS narration for every scene through `/services/ktts/v1/audio/speech`.
9. Uploads scene narration files to `/services/render/upload`.
10. Generates and uploads a full episode narration track for the final render engine voiceover.
11. Builds a 1080x1920 TikTok render payload with captions, blur background, scene effects, animated subtitle settings, and Pexels attribution metadata.
12. Submits the final render to `/services/render/render`.

The render engine accepts one global `voiceover` track, so the workflow generates per-scene narration artifacts for traceability and also creates one combined narration track for final video rendering.

## Islamic Motivation TikTok Automation Pipeline

Import:

```text
islamic_motivation_tiktok_pipeline.json
```

This workflow implements the Islamic motivation pipeline:

1. Runs once per day from an n8n Schedule Trigger.
2. Calls GPT-4o for a respectful Islamic motivational topic and narration.
3. Calls GPT-4o again for exactly five cinematic Pexels-optimized scenes.
4. Searches Pexels portrait videos scene by scene, with `nature` fallback.
5. Downloads each clip and sends it to Maester FFmpeg automation.
6. Trims and resizes each clip to 1080x1920 / 9:16.
7. Concats clips in deterministic scene order.
8. Searches Archive.org for an Islamic nasheed and continues without music if none is found.
9. Burns TikTok-style ASS captions into the video.
10. Merges nasheed audio at low volume.
11. Normalizes the final MP4 for TikTok compatibility.
12. Uploads the final file to Maester render inspection and validates duration, size, audio, and video stream metadata.
13. Uploads to TikTok if `TIKTOK_UPLOAD_ENABLED=true`; otherwise returns a dry-run render result.
14. Sends Google Sheets and Telegram status updates.

Required environment variables:

```env
MAESTER_BASE_URL=https://your-maester-space.hf.space
MAESTER_API_KEY=your_maester_api_key
OPENAI_API_KEY=your_openai_api_key
PEXELS_API_KEY=your_pexels_api_key
```

Optional publishing/logging variables:

```env
TELEGRAM_BOT_TOKEN=123456:telegram_bot_token
TELEGRAM_CHAT_ID=123456789
GOOGLE_SHEETS_WEBHOOK_URL=https://script.google.com/macros/s/your-script-id/exec
TIKTOK_UPLOAD_ENABLED=false
TIKTOK_ACCESS_TOKEN=your_tiktok_content_posting_access_token
```

Required Maester services:

```env
MAESTER_MOUNT_SERVICES=true
MAESTER_ENABLE_FFMPEG_AUTOMATION=true
MAESTER_ENABLE_RENDER_ENGINE=true
```

The workflow uses these Maester endpoints:

- `/automation/campaigns`
- `/automation/compliance/check`
- `/services/ffmpeg/n8n/execute/trim`
- `/services/ffmpeg/n8n/execute/resize_916`
- `/services/ffmpeg/n8n/execute/concat`
- `/services/ffmpeg/n8n/execute/add_subtitles`
- `/services/ffmpeg/n8n/execute/merge_music`
- `/services/ffmpeg/n8n/execute/normalize`
- `/services/render/upload`
- `/services/render/inspect`

TikTok upload is intentionally dry-run by default. Enable it only after your TikTok Content Posting API app is approved and tested.