@twick/cloud-export-video 0.14.17 → 0.14.20

package/README.md

@@ -1,129 +1,82 @@
-## @twick/cloud-export-video
+# @twick/cloud-export-video
 
-Reusable cloud-function package for exporting Twick videos. Includes a core renderer and platform templates for AWS Lambda container images.
+**Export Twick video projects to MP4 format using serverless rendering.**
 
-### Install
+Converts Twick project JSON into MP4 video files using Chromium and ffmpeg in AWS Lambda containers. No server management required—deploy as a serverless function that scales automatically.
 
-```bash
-npm install -D @twick/cloud-export-video
-```
+## What Problem Does This Solve?
 
-### CLI
+- **Serverless video rendering** — Export videos without managing servers or infrastructure
+- **Programmatic video generation** — Convert Twick project JSON to MP4 via API calls
+- **Scalable processing** — AWS Lambda handles concurrent exports automatically
+- **Cost-effective** — Pay only for rendering time, no idle server costs
 
-```bash
-npx twick-export-video help
+## Input → Output
+
+**Input:** Twick project JSON + optional media files
+```json
+{
+  "project": { /* Twick project JSON */ },
+  "mediaFiles": [ /* Optional media file URLs */ ]
+}
 ```
 
-Commands:
+**Output:** MP4 video file (base64 encoded or file path)
 
-- `init [dir]`: Scaffold AWS container template (Dockerfile + handler) into `[dir]` (default `./twick-export-video-aws`). Also writes a minimal `package.json` that depends on this package.
-- `build <image> [dir]`: Build a Docker image from `[dir]` (default `./twick-export-video-aws`).
-- `ecr-login <region> <accountId>`: Log in Docker to your AWS ECR registry.
-- `push <image> <region> <accountId>`: Tag and push the image to ECR. The repository must already exist.
+**Where it runs:** AWS Lambda container image (Linux/AMD64)
 
-### Typical flow
+## Installation
 
 ```bash
-# 1) Scaffold
-npx twick-export-video init
-
-# 2) Build an image
-npx twick-export-video build twick-export-video:latest
-
-# 3) Login to ECR
-npx twick-export-video ecr-login us-east-1 123456789012
-
-# 4) Push (assumes an ECR repo named `twick-export-video` exists)
-npx twick-export-video push twick-export-video:latest us-east-1 123456789012
+npm install -D @twick/cloud-export-video
 ```
 
-### AWS Lambda (container) usage
-
-This package ships with an AWS Lambda container template (Dockerfile + handler).
+## Quick Start
 
-#### Build image
-
-In the `packages/cloud-functions/export-video` directory:
+### 1. Scaffold AWS Lambda Template
 
 ```bash
-docker buildx build --platform linux/amd64 -t twick-export-video:latest -f platform/aws/Dockerfile .
+npx twick-export-video init
 ```
 
-#### Push image to AWS ECR
-
-To deploy the container image to AWS Elastic Container Registry (ECR) for use with Lambda:
+This creates a `twick-export-video-aws` directory with:
+- Dockerfile for Lambda container
+- Lambda handler code
+- Minimal package.json
 
-**Prerequisites:**
-- AWS CLI configured with appropriate credentials
-- Docker installed and running
+### 2. Build Docker Image
 
-**Steps:**
-
-1. **Get your AWS Account ID:**
-   ```bash
-   AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
-   ```
-
-2. **Set your AWS region and repository name:**
-   ```bash
-   AWS_REGION="your-aws-region"  # e.g., ap-south-1, us-east-1
-   REPOSITORY_NAME="twick-export-video"
-   ```
-
-3. **Login to ECR:**
-   ```bash
-   aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
-   ```
-
-4. **Create ECR repository (if it doesn't exist):**
-   ```bash
-   aws ecr create-repository \
-     --repository-name $REPOSITORY_NAME \
-     --image-scanning-configuration scanOnPush=true \
-     --region $AWS_REGION
-   ```
-
-5. **Tag the image:**
-   ```bash
-   docker tag twick-export-video:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPOSITORY_NAME:latest
-   ```
-
-6. **Push the image:**
-   ```bash
-   docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPOSITORY_NAME:latest
-   ```
-
-**Complete example script:**
 ```bash
-#!/bin/bash
-AWS_REGION="ap-south-1"
-REPOSITORY_NAME="twick-export-video"
-AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
+npx twick-export-video build twick-export-video:latest
+```
 
-# Build the image
-docker buildx build --platform linux/amd64 -t twick-export-video:latest -f platform/aws/Dockerfile .
+### 3. Deploy to AWS Lambda
 
+```bash
 # Login to ECR
-aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com
-
-# Create repository if it doesn't exist
-aws ecr create-repository --repository-name $REPOSITORY_NAME --image-scanning-configuration scanOnPush=true --region $AWS_REGION 2>/dev/null || true
+npx twick-export-video ecr-login us-east-1 YOUR_ACCOUNT_ID
 
-# Tag and push
-docker tag twick-export-video:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPOSITORY_NAME:latest
-docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPOSITORY_NAME:latest
+# Push to ECR
+npx twick-export-video push twick-export-video:latest us-east-1 YOUR_ACCOUNT_ID
 ```
 
-After pushing, you can use the ECR image URI (`$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/$REPOSITORY_NAME:latest`) when creating or updating your Lambda function.
+Then create a Lambda function using the ECR image URI.
 
-**Notes:**
-- The Dockerfile is based on `revideo/aws-lambda-base-image` and prepares Chromium and ffmpeg for headless rendering.
-- The handler expects an `event.arguments.input` payload with `{ project, mediaFiles? }`.
-- The response is a `video/mp4` base64 body, or a text file on error.
+## Deployment (High Level)
 
-### Programmatic usage
+1. **Scaffold** the Lambda container template
+2. **Build** the Docker image (includes Chromium + ffmpeg)
+3. **Push** to AWS ECR (Elastic Container Registry)
+4. **Create Lambda function** using the ECR image
+5. **Configure** memory (recommended: 3GB+) and timeout (5+ minutes)
 
-The core renderer is exported at `core/renderer.js`:
+The Lambda handler expects:
+- **Event format:** `{ arguments: { input: { project, mediaFiles? } } }`
+- **Response:** `video/mp4` base64 body, or error text
+
+## Programmatic Usage
+
+Use the core renderer directly (without Lambda):
 
 ```js
 import renderTwickVideo from '@twick/cloud-export-video/core/renderer.js';
@@ -131,4 +84,11 @@ import renderTwickVideo from '@twick/cloud-export-video/core/renderer.js';
 const resultPath = await renderTwickVideo(project, { outFile: 'my.mp4' });
 ```
 
+## Technical Details
+
+- **Base image:** `revideo/aws-lambda-base-image` (includes Chromium and ffmpeg)
+- **Platform:** Linux/AMD64
+- **Handler:** `platform/aws/handler.handler`
+- **Response format:** Base64-encoded MP4 or error text
 
+For detailed deployment steps, see the complete example script in the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twick/cloud-export-video",
-  "version": "0.14.17",
+  "version": "0.14.20",
   "description": "Twick cloud function for exporting video with platform-specific templates (AWS Lambda container)",
   "type": "module",
   "main": "core/renderer.js",
@@ -45,21 +45,18 @@
   },
   "dependencies": {
     "@sparticuz/chromium": "^129.0.0",
-    "@twick/2d": "0.14.17",
-    "@twick/core": "0.14.17",
-    "@twick/ffmpeg": "0.14.17",
-    "@twick/renderer": "0.14.17",
-    "@twick/ui": "0.14.17",
-    "@twick/vite-plugin": "0.14.17",
-    "@twick/visualizer": "0.14.17",
+    "@twick/2d": "^0.14.20",
+    "@twick/core": "^0.14.20",
+    "@twick/ffmpeg": "^0.14.20",
+    "@twick/renderer": "^0.14.20",
+    "@twick/ui": "^0.14.20",
+    "@twick/vite-plugin": "^0.14.20",
+    "@twick/visualizer": "^0.14.20",
     "@aws-sdk/client-s3": "^3.620.0",
     "ffmpeg-static": "^5.2.0",
     "fluent-ffmpeg": "^2.1.3"
   },
   "devDependencies": {
     "typescript": "~5.4.5"
-  },
-  "peerDependencies": {
-    "puppeteer": ">=22"
   }
 }