DEV Community: tsensei

I open-sourced an AI pipeline that turns any topic into a YouTube Short

tsensei — Tue, 07 Apr 2026 12:52:54 +0000

What is OpenReels?

OpenReels takes a topic and produces a YouTube Short. It handles the research, script, voiceover, visuals, music, captions, and assembly. You get a vertical MP4 at the end.

It's MIT licensed, runs via Docker Compose, and costs about $0.68 per video. You bring your own API keys.

GitHub: github.com/tsensei/OpenReels

How it works

Give it a topic. Six stages run automatically:

Stage	What happens
Research	Web search grounds the script in real facts
Script	AI creative director writes a "DirectorScore" — a per-scene production plan
Voiceover	TTS with word-level timestamps for karaoke-style captions
Visuals	AI images (Gemini, DALL-E), AI video (Veo, Kling), vision-verified stock
Music	AI-generated via Lyria 3 Pro, synced to the video's emotional arc
Assembly	Remotion composites everything with transitions and animated captions

Every stage streams progress to a web UI. You can watch it work in real time.

The DirectorScore

This is the design choice that made everything else click. Early versions generated assets independently and the results felt disconnected. The fix: make the AI write a structured plan before generating anything.

{
  "scenes": [
    {
      "sceneNumber": 1,
      "visual": {
        "type": "ai_image",
        "description": "Close-up of astronaut's visor reflecting Earth",
        "motion": { "type": "zoom_in", "intensity": "subtle" }
      },
      "voiceover": "On April 13, 1970, three men heard a bang that changed space history.",
      "transition": { "type": "crossfade", "durationMs": 500 }
    }
  ]
}

Every downstream stage reads from this score. The image generator follows the visual description, the music prompter maps the emotional arc, the caption renderer syncs to word timestamps. Same idea as film production: director writes the vision, departments execute against it.

Stock footage verification

Stock footage search is bad. Like, really bad. Search "astronaut's visor reflecting Earth" on Pexels and you get generic space B-roll.

So there's a VLM (vision-language model) that reviews each stock result and checks if it actually matches what the scene needs. Mismatch? The pipeline rewrites the search query and tries again. If stock is totally exhausted, it falls back to AI image generation.

The query reformulation step is where most of the improvement comes from. The initial search terms are rarely what stock APIs want to hear.

Music

I didn't want random background tracks. The music prompter writes a Lyria 3 Pro prompt with:

Per-scene timestamp sections
Intensity ratings (1-10)
Instrument specs
Dynamics ("sparse piano at 0:00, build strings at 0:15, full orchestra at 0:30, settle to solo cello at 0:45")

The track ducks under voiceover automatically.

Archetypes

There are 14 visual archetypes. Each one is a config that controls the entire look and feel:

anime_illustration: fast cuts, vibrant, cel-shaded
moody_cinematic: dark, slow, atmospheric
editorial_caricature: satirical, exaggerated
infographic: clean, data-heavy, rapid
pastoral_watercolor: soft, painterly
surreal_dreamscape: ethereal, impossible geometry
comic_book: bold outlines, halftone dots

They control pacing (fast: 8-12 scenes, moderate: 7-10, cinematic: 5-8), color palette, caption style, the image generation style bible, and transition defaults.

Try it

git clone https://github.com/tsensei/OpenReels.git
cd OpenReels
cp .env.example .env   # add your API keys
docker compose up      # starts Redis + API + Worker
# Open http://localhost:3000

Or single command:

docker run --env-file .env --shm-size=2gb -v ./output:/output \
  ghcr.io/tsensei/openreels "the apollo 13 disaster"

Cost

A typical video costs about $0.68:

LLM calls: $0.003 (7 calls)
TTS: $0.017
AI images: $0.30 (3 images)
AI video clip: $0.30 (1 clip)
Music: $0.08 (Lyria generation)
Stock footage: free

You can also go cheaper: --provider local uses Kokoro for voiceover (free, no API key), there's a bundled music library with 25 tracks, and you can use stock footage only.

Stack

TypeScript, Mastra, Vercel AI SDK 6, Fastify 5, BullMQ + Redis, Remotion 4, React 19, Tailwind, shadcn/ui.

Feedback welcome

I'm looking for thoughts on the architecture and the DirectorScore approach specifically. Contributors welcome too.

github.com/tsensei/OpenReels

NextJS App Router with Pocketbase SSR setup

tsensei — Wed, 06 Dec 2023 04:11:35 +0000

Pocketbase is an open-source backend solution with a single executable file. It utilizes an embedded SQLite DB and offers features like Realtime Database, Auth, File Storage, and an Admin Dashboard. This makes it a suitable option for small to medium-sized projects where alternatives like Supabase might be excessive. Pocketbase runs efficiently on a small VPS and can handle thousands of users with ease.

With the advent of React Server Components and NextJS's App Router, we now have two environments for running code and rendering UI: server and client. By default, Pocketbase stores the auth token pocketbase_auth in localStorage, which is not accessible on the server. This limitation can be problematic when rendering user-specific data or redirecting to a login route if the user is not authenticated. A workaround is to store the auth token in a cookie, making it accessible across all environments and sent with every request by default.

The Pocketbase JS SDK allows for the creation of custom auth stores for more fine-grained control. In this tutorial, however, we will follow a similar approach to @supabase/ssr, which involves two functions:

createBrowserClient : This function instantiates a browser client for client components and synchronizes the cookie with localStorage.
createServerClient : This function instantiates a server client, allowing you to pass a cookieStore to access user auth details.

Let's get down to code without further ado :

Download Pocketbase, extract and launch the executable with ./pocketbase serve
This will provide with a API URL which you can write in your .env file. In my case :

NEXT_PUBLIC_POCKETBASE_API_URL=http://127.0.0.1:8090/

The NEXT_PUBLIC_ prefix is necessary for it to be accessible in client environment.

For Typescript IntelliSense support, generate the types using pocketbase-typegen. I have stored it in src/types/pocketbase-types.ts.

With the configurations in place, I have a ./src/lib/pocketbase.ts file to store my functions.

For client components :

import { TypedPocketBase } from '@/types/pocketbase-types';
import PocketBase from 'pocketbase';

let singletonClient: TypedPocketBase | null = null;

export function createBrowserClient() {
    if (!process.env.NEXT_PUBLIC_POCKETBASE_API_URL) {
        throw new Error('Pocketbase API url not defined !');
    }

    const createNewClient = () => {
        return new PocketBase(
            process.env.NEXT_PUBLIC_POCKETBASE_API_URL
        ) as TypedPocketBase;
    };

    const _singletonClient = singletonClient ?? createNewClient();

    if (typeof window === 'undefined') return _singletonClient;

    if (!singletonClient) singletonClient = _singletonClient;

    singletonClient.authStore.onChange(() => {
        document.cookie = singletonClient!.authStore.exportToCookie({
            httpOnly: false,
        });
    });

    return singletonClient;
}

This returns a PocketBase instance using the singleton pattern, it also syncs the cookie with localStorage - so you don't have to think of auth state changes - everything should just work!

For Server components :

import { TypedPocketBase } from '@/types/pocketbase-types';
import { ReadonlyRequestCookies } from 'next/dist/server/web/spec-extension/adapters/request-cookies';
import PocketBase from 'pocketbase';

export function createServerClient(cookieStore?: ReadonlyRequestCookies) {
    if (!process.env.NEXT_PUBLIC_POCKETBASE_API_URL) {
        throw new Error('Pocketbase API url not defined !');
    }

    if (typeof window !== 'undefined') {
        throw new Error(
            'This method is only supposed to call from the Server environment'
        );
    }

    const client = new PocketBase(
        process.env.NEXT_PUBLIC_POCKETBASE_API_URL
    ) as TypedPocketBase;

    if (cookieStore) {
        const authCookie = cookieStore.get('pb_auth');

        if (authCookie) {
            client.authStore.loadFromCookie(`${authCookie.name}=${authCookie.value}`);
        }
    }

    return client;
}

You can choose to pass it a cookieStore to have the user specific auth store loaded or you can ignore the parameter if you are just using it to fetch general data on the server. Examples for both cases is provided below.

With all the code in place, your pocketbase.ts should look like this :

import { TypedPocketBase } from '@/types/pocketbase-types';
import { ReadonlyRequestCookies } from 'next/dist/server/web/spec-extension/adapters/request-cookies';
import PocketBase from 'pocketbase';

let singletonClient: TypedPocketBase | null = null;

export function createBrowserClient() {
    if (!process.env.NEXT_PUBLIC_POCKETBASE_API_URL) {
        throw new Error('Pocketbase API url not defined !');
    }

    const createNewClient = () => {
        return new PocketBase(
            process.env.NEXT_PUBLIC_POCKETBASE_API_URL
        ) as TypedPocketBase;
    };

    const _singletonClient = singletonClient ?? createNewClient();

    if (typeof window === 'undefined') return _singletonClient;

    if (!singletonClient) singletonClient = _singletonClient;

    singletonClient.authStore.onChange(() => {
        document.cookie = singletonClient!.authStore.exportToCookie({
            httpOnly: false,
        });
    });

    return singletonClient;
}

export function createServerClient(cookieStore?: ReadonlyRequestCookies) {
    if (!process.env.NEXT_PUBLIC_POCKETBASE_API_URL) {
        throw new Error('Pocketbase API url not defined !');
    }

    if (typeof window !== 'undefined') {
        throw new Error(
            'This method is only supposed to call from the Server environment'
        );
    }

    const client = new PocketBase(
        process.env.NEXT_PUBLIC_POCKETBASE_API_URL
    ) as TypedPocketBase;

    if (cookieStore) {
        const authCookie = cookieStore.get('pb_auth');

        if (authCookie) {
            client.authStore.loadFromCookie(`${authCookie.name}=${authCookie.value}`);
        }
    }

    return client;
}

Protected Route Guarding

You can have a middleware.ts in the src directory or your project root to guard protected routes and redirect unauthenticated users to a auth route :

import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { createServerClient } from './lib/pocketbase';

// For protected pages
// If auth is not valid for matching routes
// Redirect to a redirect path
export function middleware(request: NextRequest) {
    const redirect_path = 'http://localhost:3000/auth';

    const cookieStore = cookies();

    const { authStore } = createServerClient(cookieStore);

    if (!authStore.isValid) {
        return NextResponse.redirect(redirect_path);
    }
}

export const config = {
    matcher: [
        /*
         * Match all request paths except for the ones starting with:
         * - api (API routes)
         * - _next/static (static files)
         * - _next/image (image optimization files)
         * - favicon.ico (favicon file)
         * - auth (login route)
         * - / (root path)
         */
        '/((?!api|_next/static|_next/image|favicon.ico|auth|^$).*)',
    ],
};

All routes except the ones in matcher should be protected by default now. You will have to manually exclude your intended public routes by modifying the matcher regex.

Examples :

Personalized Route :

import { createServerClient } from '@/lib/pocketbase';
import { cookies } from 'next/headers';

const Page = async () => {
    const cookieStore = cookies();

    const pocketbase = createServerClient(cookieStore);

    const posts = await pocketbase.collection('posts').getFullList();

    return <pre>{JSON.stringify(posts, null, 3)}</pre>;
};

export default Page;

In this example, we have passed our cookie store and in the DB we have this rule in place - List/Search rule : @request.auth.id != "" && @request.auth.id = author.id. As we passed our cookie store, the requests will have a auth store and respond with user specific posts.

For general posts which can be listed by anyone, you can ignore the cookieStore and get the data accordingly. Keep in mind, calling the cookies() function will opt the page into dynamic rendering.

Error Handling :

Sometimes the errors can be hard to debug, in which case, wrap your operation in a try-catch block and log the error.originalError to get more details.

try {
    const posts = await pocketbase.collection('posts').getFullList();
} catch (error: any) {
    console.log(error.originalError);
}

Note : Keep in mind, with the API Rules in place, you can call PocketBase directly from your client in case of any mutations, effectively removing the API Layer we had before. It will update the token automatically - for example in case of logout, the SDK will remove the token from localStorage and our browserClient will sync accordingly, removing the token from cookie as well.

I hope this writing to be of help. You can ask any questions or suggest any fix in case of issue. You can leave a ❤️ & follow me on Github.

Modules in NodeJS : ESM vs CommonJS

tsensei — Thu, 04 May 2023 07:59:01 +0000

NodeJS Module Types :

NodeJS has three module types :

Core Modules : These are built-in modules that are part of Node.js distribution and are availabe globally without needing to install any additional distribution. Example : fs, http, etc.
Local Modules : Custom modules written by developers and saved as individual files.
Third-Party Modules : Written by external developers, installed and managed by Node Package Manager (NPM).

NodeJS Module Systems :

Node provides us with 2 module system to work with modules :

CommonJS : It is the original way to work with modules using the require() syntax to import and module.exports to export modules.
ESM (ECMAScript modules): Newer module system introduced in es6. It uses import to import modules and export to export modules.

Module Importing Priority : core modules > third party modules (node_modules) > local modules

CommonJS :

Importing :

In CommonJS syntax, we import using the require() function. When the require function is invoked, Node goes through the following steps :

Resolving
Loading
Wrapping : Code inside the module is wrapped in a special wrapper which gives the encapsulation and provides with some special properties :

  (function (exports, require, module, __filename, __dirname) {
    // Module code lives in here
  });

Evaluating : Node executes the code within the wrapeer and exports function and variables mentioned in module.exports
Caching : Modules are cached after loading for the first time. So, any later loading of the module simply returns the cached value without executing it again. Caching will be discussed in details in a later section.

By wrapping the code in this wrapper, Node.js achieves a few things :

It keeps top-level variables (defined with var, const, or let) scoped to the module rather than the global object.
It helps to provide some global-looking variables that are actually specific to the module, such as: __filename and __dirname

Exporting :

In CommonJS, we can export variables or functions with the export property of the module object provided by the wrapper.

For default export, we can set our module.export directly to whatever we want to export. Also, In the importing file, we don't need to match the name of the exported variable/function, as we can have only one default export per module.

  // my-module.js

  function hello(name) {
    console.log(`Hello, ${name}!`);
  }

  module.exports = hello;

  // app.js

  const whateverYouNameIt = require("./my-module");

  hello("world");

Logging the module object in my-module.js gives us:

  Module {
    id: '.',
    path: '/home/user/Lessons/nodejs',
    exports: [Function: hello],
    filename: '/home/user/Lessons/nodejs/module.js',
    loaded: false,
    children: [],
    paths: [
      ...
    ]
  }

For named export, we can bind all our exportable variables/functions to the module.exports object. Then we can destructure to use specific ones.

  // my-module.js

  function hello(name) {
    console.log(`Hello, ${name}!`);
  }

  module.exports = {
    hello,
  };

or,

  // my-module.js

  module.exports.hello = function (name) {
    console.log(name);
  };

  // app.js

  const { hello } = require("./my-module");

  hello("world");

Logging the module object in my-module.js gives us:

  Module {
    id: '.',
    path: '/home/user/Lessons/nodejs',
    exports: { hello: [Function: hello] },
    filename: '/home/user/Lessons/nodejs/module.js',
    loaded: false,
    children: [],
    paths: [
      ...
    ]
  }

exports vs module.exports :

From the wrapper, we get a exports object, this is just a reference to the module.exports object. So, whatever we add to the export object, gets added to the module.exports as well. But if we reassign export with some variable/function in hope of default exporting, the link is broken, and module.exports will return an empty object.

ECMAScript Modules :

Importing :

To use import syntax, we need to set "type" : "module" in package.json.

Different than CommonJS module, in ESM module,
import {myFunction} from "./circle.js"
and,
import {myFunction} from "./circle"
isn't the same.

because, in ESM we can import other type of modules beside JS files like JSON or CSS files, and specifying the extension is necessary to disambiguate between them.

When import is invoked, Node goes through the following steps :

Resolving : The resolving algorithm is different than that of CommonJS.
Loading
Wrapping : There is no wrapper for ES modules. they are native to the underlying JS engine. Specifically, ECMAScript modules have their own module scope, which means that the variables and functions defined in an ECMAScript module are not global.
Evaluating: Node executes the code within the module.
Caching: Modules are cached after loading for the first time. So, any later loading of the module simply returns the cached value without executing it again.

Exporting :

In ESM, we have export for named exports and export default for default exports.

// my-module.js

export function hello(name) {
  console.log(`Hello, ${name}!`);
}

export default function logger(message) {
  console.log(message);
}

// app.js

import whateverYouNameIt, { hello } from "./my-module.js";

whateverYouNameIt("custom message"); // calls the logger function, we can name it anything because of it being a default export

hello("world");

We can have multiple exports from a module, but only one default export.

Module caching :

Caching :

When loading a module, NodeJS executes the code once and caches the result. On subsequent imports from same or other modules, it returns the cached results.

Caching example in CommonJS :

Let's do a little fun experiment to see this in action.

In one.js :

// We generate the current timestamp and add 5 to it
// so, each time we execute this following code, we will have different results

console.log("one.js execution started");

let timestamp = Date.now();
let number = 5;

let sum = timestamp + number;

module.exports = {
  sum,
};

In two.js :

// This file imports the time dependant sum
// but executes after a 5 seconds delay
// We export a dummy variable from this file to reference in three.js

console.log("two.js execution started");

console.log("Loop started");
const startTime = Date.now();
while (Date.now() < startTime + 5000) {}
console.log("Loop finished after 5 seconds");

const { sum } = require("./one");

console.log(`Sum within two.js is ${sum}`);

let dummy = 8;

module.exports = {
  dummy,
};

In three.js :

// This file imports both one.js and two.js

console.log("three.js execution started");

const { sum } = require("./one");

console.log(`Sum within three.js is ${sum}`);

// two.js is imported after getting the sum from one.js

const { dummy } = require("./two");

Intuitively, when we run three.js with node three.js, we expect it:

Log "three.js execution started"
Import the one.js module and execute its code
Log "Sum within three.js is (current timestamp + 5)" with the current time of execution.
Importing two.js module starts the 5 seconds loop and then requires the one.js file to get the sum. So, technically, timestamp is in seconds, so for five seconds delay, we can expect some difference
The log within two.js should generate a sum greater than the one logged in three.js due to difference in execution time.

So, log output should be something like this :

three.js execution started
one.js execution started
Sum within three.js is 1683184022476
two.js execution started
Loop started
Loop finished after 5 seconds
Sum within two.js is 1683184022481

But, what we really get is this :

three.js execution started
one.js execution started
Sum within three.js is 1683184022476
two.js execution started
Loop started
Loop finished after 5 seconds
Sum within two.js is 1683184022476

Even with the five seconds loop, we get the same value for sum which is dependant on time !

So, by now we should be clear that NodeJS when importing a module for the first time, executes the code once and caches the result for future imports.

Caching example in ESM :

// my-module.js

let count = 0;

console.log("Module loaded");

export function increment() {
  count++;
}

export function getCount() {
  return count;
}

// app.js

import { increment, getCount } from "./my-module.js";

console.log("Import 1");
increment();
console.log(getCount()); // 1

console.log("Import 2");
increment();
console.log(getCount()); // 2

//some-other-file.js

// Import the module again from a different file
import { getCount } from "./my-module.js";
console.log(getCount()); // 2 (the same value as the previous call to getCount())

References used :

More details on the underlying workings can be found at NodeJS specification :

I created a SpaceX tracker with React

tsensei — Tue, 03 Aug 2021 13:49:03 +0000

Hey fellow React dev/spaceX fan,

https://tsensei.github.io/spaceXtale/

This webapp contains a countdown timer for latest launch, all info about past and upcoming launches and detailed info about rockets and starlink satellites.

No external librarys were used except for react-router-dom, everything is coded from the ground up. Any review or constructive criticism would be appreciated.