rain

Social Media content generation tool for Earth App

rain is the official content generation tool for Earth App. It uses the Earth App API to fetch data about activities, events, prompts, and articles, and generates images with the content formatted in a visually appealing way.

Usage

Photo Generation

bun run photo:<type>

Where <type> is one of activity, event, prompt, or article.

Video Generation

bun run video:prompt

This command generates a vertical short-form video at out/prompt.mp4.

Related commands:

• bun src/videos/generate-prompt.ts --skip-render generates narration audio, out/prompt.props.json, and out/prompt.manifest.json without invoking Remotion.
• bun run video:studio opens the Remotion Studio for previewing and iterating on the composition.
• bun run upload:prompt uploads the generated prompt video to YouTube.

Pipeline:

1. Fetch one random prompt from the Earth API.
2. Read the prompt aloud with Cloudflare TTS.
3. Generate an answer with Granite 4.0 H Micro using the Cloud system prompt.
4. Read the answer aloud with Cloudflare TTS.
5. Build timed captions from prompt and answer text.
6. Animate cloud variants while narration is active.
7. Render with Remotion over a random Minecraft background window.

Additional outputs:

• out/prompt.props.json: Render props passed into Remotion.
• out/prompt.manifest.json: Generation metadata (durations, assets, text).
• src/assets/generated/prompt-*/: Generated narration audio files for the most recent prompt runs.

Video Notes

• Target format: 1080x1920 at 30fps.
• Timing flow (hook-led): the spoken hook lands at frame 0 — there is no spoken question and no opening pause. The reframed question shows as an on-screen "topic card" for the first ~2.2s, then karaoke captions carry the rest. The end loops back to the hook for seamless replays.
• Duration policy (driven by LENGTH_PROFILE, default short):
  • Hard range: 30-60s, centered near 42s (the retention sweet spot for Shorts).
• Captions: word-level karaoke (FEATURE_WORD_CAPTIONS), large and center-safe.
• Background: one of three rotated templates (broll-kinetic, motion-type, gameplay) chosen per video and tagged in the manifest for the optimizer.
  • broll-kinetic: topic-matched stock B-roll (Pexels/Pixabay) + kinetic typography.
  • motion-type: animated gradient + oversized kinetic typography (no stock dependency).
  • gameplay: the legacy Minecraft window (intentionally rare).
• Watermark: persistent Earth App logo at bottom-right; thin progress bar along the bottom.

B-roll / stock footage keys

broll-kinetic pulls vertical clips from free stock APIs. Set either key (Pixabay alone is enough; Pexels is recommended for more coverage and is tried first):

• PEXELS_API_KEY — free at https://www.pexels.com/api/.
• PIXABAY_API_KEY — free at https://pixabay.com/api/docs/.

Toggles (all default on): FEATURE_STOCK_BROLL, FEATURE_KINETIC_TYPOGRAPHY. With no keys set, broll-kinetic folds into motion-type so renders never break. Attribution for each fetched clip is recorded in out/prompt.manifest.json under brollSources.

Implementation approach (research-aligned):

• Use OffthreadVideo for stable frame-accurate background extraction.
• Use dynamic composition duration (calculateMetadata) so renders end with narration.
• Keep generation side effects out of the composition by precomputing all timing data in Bun.
• Use deterministic render props (prompt.props.json) for reproducible output/debugging.

Contributing

Contributions are welcome! Please open an issue or submit a pull request with your changes.

Licensed under the Apache License, Version 2.0. See LICENSE for more information.