itsgiving

A treatment agent for music-video and short-film directors: it reads an audience's taste on Qloo and turns it into a pitch deck with receipts. Your voice, their taste.

Comment

Inspiration

I make short films. Before a music video or a short gets made, the director writes a treatment: the concept, reference films, wardrobe, locations, a palette. It is how you win the job, and it is mostly guesswork about who the audience is. Directors bring their own taste; the audience brings theirs. I wanted a tool that puts the two in one document, with the evidence showing: your voice, their taste.

What it does

You give itsgiving an artist (for a music video) or the films a short is after, a city and a budget, and optionally your own films (a TMDB list or IMDb links). In about a minute it returns a full treatment:

  • Concept and logline, with the audience's tone tags beside them
  • Reference films and series this audience loves, with deep-cut and era controls and TMDB stills
  • Beats and characters: each character drawn from a character in a title the audience loves, with a face this audience knows as a casting reference
  • Wardrobe from fashion brands the audience over-indexes on, with Qloo's style notes and price ranges, flagged when above budget
  • Locations: real venues near a shoot base picked from Qloo's heatmap of where the audience lives in that city, on a contour map over OpenStreetMap
  • Camera, light and palette, plus the audience read and how it ranks the director's own films

Every pick carries a receipt: its rank of N for this audience, its affinity, and which input drove it. Qloo's evidence and the model's interpretation are kept visually separate. You can rework it ("darker", "more 90s", "deeper cuts", "cheaper locations"), pick a title card face or a world-cinema era look, save it as a PDF, or sign in to save and share it.

How I built it

  • Next.js 16 / React 19 / Tailwind 4 on Vercel, TypeScript throughout.
  • A lean agent: code runs the Qloo tools deterministically; the LLM makes at most 3 calls per treatment (normally 2): one plans (creative direction and tool parameters, using only IDs the tools returned), one writes the treatment as structured JSON that may cite only returned items. Citations are short refs checked by per-request schemas, so the model cannot invent a film, brand or place. Every output is validated with zod, with one repair try and a fallback chain (DeepSeek, then Gemini, then Groq).
  • 12 tools over Qloo's REST API (called directly rather than through the starter harness, because it runs serverless and needs filters the harness lacks): /search for names and cities, /entities for IMDb imports, /v2/tags for style words, /v2/insights for audience taste, films, series, actors, artists, brands, places and the heatmap, /v2/analysis/compare for the director-vs-audience overlap, and filter.results.entities to rank the director's own films for this audience.
  • TMDB for film stills, character names and actors' known roles; OpenStreetMap tiles under the heatmap's contour lines (d3-contour); Supabase for sign-in, saving and share links.
  • Featured treatments are pre-built at deploy, so judges never depend on live rate limits, and the live studio still builds new ones.

Challenges I ran into

  • Qloo ignores bad parameters silently: an empty 200 usually meant a wrong filter, so every tag and audience ID is resolved before use.
  • "New York" matched New York State, which put venues 200 km upstate; cities are now resolved as localities first.
  • Short films aren't in Qloo, so a short is described by the feature films it's after.
  • Rate limits on Vercel: functions sit about 11 ms from Qloo, so parallel calls burst past 10 requests a second; a shared pacer fixed it.
  • Heatmaps are big (up to 1 MB, thousands of tiles), so they're grouped into named areas before anything reaches the model.
  • Free LLM tiers were too slow or too weak for a minute-long run; blind-judged benchmarks led to DeepSeek with deep thinking first.
  • Safety: identity tags (orientation, religion, ethnicity, health, politics) are filtered out before the planner ever sees them; no inference about individuals.

What I learned

Taste data is most useful when it stays visible. Directors trust a pick when they can see why it is there, so the receipts became the product's voice, and the model's writing sits beside them rather than replacing them.

Limitations

Affinities describe audiences, not any one person. Qloo has no short films or songs (music is artist-level), so those come in as context only. Venues still need filming permission, and casting faces are references for a part, not offers.

What's next

Ad and commercial treatments as a third format, and more world-cinema eras.

Built With

Share this project:

Updates

Submission history