fix issues

packages/client/.gitignore

@@ -0,0 +1,177 @@
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+dist
+.nuxt
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
+# TypeScript build information
+*.tsbuildinfo

packages/client/.npmignore

@@ -0,0 +1,4 @@
+# Ignore everything
+*
+# Except the dist directory
+!dist/

packages/client/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "printWidth": 140,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "bracketSpacing": true
+}

packages/client/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Julian Bilcke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/client/README.md

@@ -0,0 +1,113 @@
+# @aitube/client
+
+*Official API client for AiTube.at*
+
+## ATTENTION
+
+AiTube is currently in heavy development, and for the moment
+the API client is reserved for *private use* (it is used by AI Stories Factory).
+
+We are sorry for any inconvenience this might cause.
+
+## Caveats
+
+The official domain for AiTube is `aitube.at`, however right now
+the Hugging Face Space is not configured to use this as a domain,
+so we need to perform all API calls to `jbilcke-hf-ai-tube.hf.space`.
+
+## Installation
+
+To install the package, run the following command:
+
+```bash
+npm install @aitube/client
+```
+
+## Getting Started
+
+Note: to overridethe AiTube API URL, set this env var: `AITUBE_URL`
+
+```typescript
+import {
+  createClap,
+  editClapDialogues,
+  editClapEntities,
+  editClapMusic,
+  editClapSounds,
+  editClapStory,
+  editClapStoryboards,
+  editClapVideos,
+  exportClapToVideo,
+  defaultAitubeHostname,
+  defaultClapWidth,
+  defaultClapHeight,
+  defaultExportFormat,
+  aitubeUrl,
+  aitubeApiVersion,
+  aitubeApiUrl,
+  ClapEntityPrompt,
+  SupportedExportFormat,
+  applyClapCompletion,
+ } from '@aitube/client'
+
+const ultraSecret = "ultra secret token unavailable to common mortals"
+
+const basicClap = await createClap({
+  prompt: "story about a dog",
+  turbo: false,
+  token: ultraSecret
+})
+
+const illustratedClap = await editClapStoryboards({
+  clap: basicClap,
+  turbo: false,
+  token: ultraSecret
+})
+
+const mp4VideoFile = await exportClapToVideo({
+  clap: illustratedClap,
+  format: "mp4",
+  turbo: false,
+  token: ultraSecret
+})
+```
+
+## Customizing the server
+
+The hostname can be overriden by defining the `AITUBE_URL` environment variable.
+
+eg:
+
+```bash
+AITUBE_URL=http://localhost:3000
+```
+
+## Build Instructions
+
+Install [Bun](https://bun.sh/)
+
+Run the following commands:
+
+```bash
+bun install
+
+bun run build
+```
+
+To publish:
+
+```bash
+bun run build
+
+bun run build:declaration
+
+bun run publish
+```
+
+## Contributing
+
+We welcome contributions! Please feel free to submit a pull request.
+
+## License
+
+This package is under the MIT License. See `LICENSE` file for more details.

packages/client/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@aitube/client",
+  "module": "index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "version": "0.2.4-3",
+  "description": "Official API client for AiTube.at",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outfile=dist/index.js --external=@aitube/clap && bun run build:declaration",
+    "build:declaration": "tsc --emitDeclarationOnly --project tsconfig.types.json",
+    "postbuild": "rimraf tsconfig.types.tsbuildinfo && bun run build:declaration",
+    "publish": "npm publish --access public",
+    "update": "rm -Rf node_modules && rm bun.lockb && bun i && bun run build"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "prettier": "^3.3.3",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.5.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jbilcke-hf/aitube-client.git"
+  },
+  "keywords": [
+    "Clapper.app",
+    "AiTube.at",
+    "OpenClap",
+    "AI cinema",
+    "file format",
+    "specification"
+  ],
+  "author": "Julian Bilcke",
+  "license": "MIT",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "dist/**/*.d.ts"
+  ],
+  "dependencies": {
+    "@aitube/clap": "workspace:*",
+    "@types/bun": "latest",
+    "query-string": "^9.0.0"
+  }
+}

packages/client/src/api/createClap.ts

@@ -0,0 +1,43 @@
+import { ClapProject, fetchClap } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+
+import { defaultClapHeight, defaultClapWidth } from "@/constants/defaultValues"
+
+export async function createClap({
+  prompt,
+  height = defaultClapHeight,
+  width = defaultClapWidth,
+  turbo = false,
+  token,
+}: {
+  prompt: string
+  height?: number
+  width?: number
+  turbo?: boolean
+  token?: string
+}): Promise<ClapProject> {
+  
+  if (typeof prompt !== "string" || !prompt.length) { throw new Error(`please provide a prompt`) }
+
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const clap = await fetchClap(`${aitubeApiUrl}create`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: JSON.stringify({
+      prompt,
+      width,
+      height,
+      turbo,
+    }),
+    cache: "no-store",
+  })
+
+  return clap
+}

packages/client/src/api/editClapDialogues.ts

@@ -0,0 +1,61 @@
+import { ClapCompletionMode, ClapProject, fetchClap, removeGeneratedAssetUrls, serializeClap } from "@aitube/clap"
+import queryString from "query-string"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapDialogues({
+  clap,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a valid clap project`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+  
+  const newClap = await fetchClap(
+    `${aitubeApiUrl}edit/dialogues?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapEntities.ts

@@ -0,0 +1,75 @@
+import { ClapCompletionMode, ClapProject, fetchClap, serializeClap, removeGeneratedAssetUrls } from "@aitube/clap"
+import queryString from "query-string"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { ClapEntityPrompt } from "@/constants/types"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapEntities({
+  clap,
+  entityPrompts = [],
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  // A ClapProject instance
+  clap: ClapProject
+
+  // a list of entity prompts
+  entityPrompts?: ClapEntityPrompt[],
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a clap to extend`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  if (entityPrompts.length) {
+    // if "params.e = JSON.stringify(item)" works with UTF-8 characters,
+    // then we don't need to import "js-base64"
+    // otherwise you will have to do:
+    // params.e = jsBase64.encode(JSON.stringify(item))
+    params.e = JSON.stringify(entityPrompts)
+  }
+
+  const newClap = await fetchClap(
+    `${aitubeApiUrl}edit/entities?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapMusic.ts

@@ -0,0 +1,60 @@
+import queryString from "query-string"
+import { ClapCompletionMode, ClapProject, fetchClap, serializeClap, removeGeneratedAssetUrls } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapMusic({
+  clap,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+  
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a valid clap project`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/music?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapSounds.ts

@@ -0,0 +1,60 @@
+import queryString from "query-string"
+import { ClapCompletionMode, ClapProject, fetchClap, serializeClap, removeGeneratedAssetUrls } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapSounds({
+  clap,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+  
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a valid clap project`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/sounds?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapStory.ts

@@ -0,0 +1,114 @@
+import { ClapCompletionMode, ClapProject, fetchClap, filterAssets, isValidNumber, serializeClap, removeGeneratedAssetUrls } from "@aitube/clap"
+import queryString from "query-string"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapStory({
+  clap,
+  prompt,
+  startTimeInMs,
+  endTimeInMs,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  // A ClapProject instance
+  clap: ClapProject
+
+  // a prompt to describe how to extend the story (optional)
+  prompt?: string
+
+  // indicates where the completion should start in the timeline
+  //
+  // this can be used tp jump to arbitrary timestamps
+  // in the story
+  //
+  // if you pick a start time AFTER the current project's end time,
+  // the project will be extended
+  //
+  // default value: the current project's end time
+  startTimeInMs?: number
+
+  // it is recommended to use a
+  // end time (eg. startTimeInMs + 12000)
+  // if left by default, th server will generate
+  //
+  // for performance and security reasons,
+  // the server may enforce a hardcoded limit to bypass what you
+  // set here, but that is not a big deal because you can pass
+  // you .clap file again if necessary
+  //
+  // default value: no limit (the server will set one)
+  endTimeInMs?: number
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a clap to extend`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (typeof prompt === "string" && prompt.length > 0) {
+    params.p = prompt
+  }
+
+  if (isValidNumber(startTimeInMs)) {
+    params.s = startTimeInMs
+  }
+
+  if (isValidNumber(endTimeInMs)) {
+    params.e = endTimeInMs
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  // we remove heavy elements from the payload
+  const payload = await filterAssets({
+    clap,
+    mode: "INCLUDE",
+    categories: {},
+    immutable: true, // to create a standalone copy
+
+    // we only remove the data, but we still keep things marked as "generated"
+    updateStatus: false,
+  })
+  
+  const newClap = await fetchClap(
+    `${aitubeApiUrl}edit/story?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapStoryboards.ts

@@ -0,0 +1,60 @@
+import queryString from "query-string"
+import { ClapCompletionMode, ClapProject, fetchClap, serializeClap, removeGeneratedAssetUrls } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapStoryboards({
+  clap,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a valid clap project`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/storyboards?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(removeGeneratedAssetUrls(clap)),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/editClapVideos.ts

@@ -0,0 +1,85 @@
+import queryString from "query-string"
+import { ClapCompletionMode, ClapProject, fetchClap, serializeClap, removeGeneratedAssetUrls, ClapSegmentStatus, ClapSegmentCategory, filterSegments, ClapSegmentFilteringMode, ClapSegment } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { applyClapCompletion } from "@/utils"
+
+export async function editClapVideos({
+  clap,
+  completionMode = ClapCompletionMode.MERGE,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+  
+  /**
+   * Completion mode (optional, defaults to "merge")
+   * 
+   * Possible values are:
+   * - full: the API and the client will return a full clap file. This is a very convenient and simple mode, but it is also very ineficient, so it should not be used for intensive applications.
+   * - partial: the API and the client will return a partial clap file, containing only the new values and changes. This is useful for real-time applications and streaming.
+   * - merge: the API will return a partial clap file, and the client will return a merge of the original with the new values. This is safe to run, there are no side-effects.
+   * - replace: the API will return a partial clap file, and the client will replace the original. This is the most efficient mode, but it relies on side-effects and inline object updates. 
+   */
+  completionMode?: ClapCompletionMode
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<ClapProject> {
+
+  if (!clap) { throw new Error(`please provide a valid clap project`) }
+  
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const params: Record<string, any> = {}
+
+  if (typeof completionMode === "string") {
+    params.c = completionMode
+  }
+
+  if (turbo) {
+    params.t = "true"
+  }
+  // special trick to not touch the generated
+  // storyboard images that are used by pending videos
+  const idsOfStoryboardsToKeep = clap.segments.map((segment: ClapSegment) => {
+    
+    const isPendingVideo = (
+      segment.category === ClapSegmentCategory.VIDEO
+      &&
+      segment.status === ClapSegmentStatus.TO_GENERATE
+    )
+
+    if (!isPendingVideo) { return undefined }
+
+    const storyboardImage: ClapSegment | undefined = filterSegments(
+      ClapSegmentFilteringMode.BOTH,
+      segment,
+      clap.segments,
+      ClapSegmentCategory.IMAGE
+    ).at(0)
+
+    return storyboardImage?.id
+  }).filter((x: any) => x) as string[]
+
+  const newClap = await fetchClap(`${aitubeApiUrl}edit/videos?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(
+      // need a special trick here, to not touch the generated
+      // storyboards that are used by pending videos
+      removeGeneratedAssetUrls(clap, idsOfStoryboardsToKeep)
+    ),
+    cache: "no-store",
+  })
+
+  const result = await applyClapCompletion(clap, newClap, completionMode)
+
+  return result
+}

packages/client/src/api/exportClapToVideo.ts

@@ -0,0 +1,60 @@
+import queryString from "query-string"
+import { ClapProject, serializeClap, blobToDataUri } from "@aitube/clap"
+
+import { aitubeApiUrl } from "@/constants/config"
+import { defaultExportFormat, SupportedExportFormat } from "@/constants"
+
+
+export async function exportClapToVideo({
+  clap,
+  format = defaultExportFormat,
+  turbo = false,
+  token,
+}: {
+  clap: ClapProject
+
+  /**
+   * Desired output video format (defaults to "mp4")
+   * 
+   * Can be either "mp4" or "webm"
+   */
+  format?: SupportedExportFormat
+
+  turbo?: boolean
+
+  token?: string
+}): Promise<string> {
+  
+  if (!clap) { throw new Error(`please provide a clap`) }
+
+  // TODO use an enum instead, and check the enum object
+  if (format !== "mp4" && format !== "webm") { throw new Error(`please provide a valid format ("${format}" is unrecognized)`) }
+
+  const params: Record<string, any> = {}
+
+  params.f = format
+
+  if (turbo) {
+    params.t = "true"
+  }
+
+  const hasToken = typeof token === "string" && token.length > 0
+
+  const res = await fetch(`${aitubeApiUrl}export?${queryString.stringify(params)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-gzip",
+      ...hasToken && {
+        "Authorization": `Bearer ${token}`
+      }
+    },
+    body: await serializeClap(clap),
+    cache: "no-store",
+  })
+
+  const blob = await res.blob()
+
+  const dataURL = await blobToDataUri(blob)
+  
+  return dataURL
+}

packages/client/src/api/index.ts

@@ -0,0 +1,9 @@
+export { createClap } from "./createClap"
+export { editClapDialogues } from "./editClapDialogues"
+export { editClapEntities } from "./editClapEntities"
+export { editClapMusic } from "./editClapMusic"
+export { editClapSounds } from "./editClapSounds"
+export { editClapStory } from "./editClapStory"
+export { editClapStoryboards } from "./editClapStoryboards"
+export { editClapVideos } from "./editClapVideos"
+export { exportClapToVideo } from "./exportClapToVideo"

packages/client/src/constants/config.ts

@@ -0,0 +1,16 @@
+import { defaultAitubeHostname } from "./defaultValues"
+
+// we leave the opportunity to override this at runtime
+export const aitubeUrl = `${
+  process.env.AITUBE_URL ||
+  `https://${defaultAitubeHostname}`
+}`
+
+// note: let's keep it simple and only support one version at a time
+export const aitubeApiVersion = "v1"
+
+export const aitubeApiUrl = `${
+  aitubeUrl
+}${
+  aitubeUrl.endsWith("/") ? "" : "/"
+}api/${aitubeApiVersion}/`

packages/client/src/constants/defaultValues.ts

@@ -0,0 +1,10 @@
+// unfortunately, this doesn't work yet due to a redirection issue
+// const defaultAitubeHostname = "aitube.at"
+
+// so we have to use the direct space hostname instead
+export const defaultAitubeHostname = "aitube.at"
+
+export const defaultClapWidth = 512
+export const defaultClapHeight = 288
+
+export const defaultExportFormat = "mp4"

packages/client/src/constants/index.ts

@@ -0,0 +1,17 @@
+export {
+  defaultAitubeHostname,
+  defaultClapWidth,
+  defaultClapHeight,
+  defaultExportFormat
+} from './defaultValues'
+
+export {
+  aitubeUrl,
+  aitubeApiVersion,
+  aitubeApiUrl
+} from './config'
+
+export {
+  ClapEntityPrompt,
+  SupportedExportFormat
+} from "./types"

packages/client/src/constants/types.ts

@@ -0,0 +1,25 @@
+import { ClapSegmentCategory } from "@aitube/clap"
+
+export type SupportedExportFormat = "mp4" | "webm"
+
+export type ClapEntityPrompt = {
+  name: string
+
+  // eg. "character", "location"
+  category: ClapSegmentCategory
+
+  // age of the person, animal or entity (eg. robot, talking spaceship etc)
+  age: string
+
+  // characterization of the person, animal or entity (texture, hair color, gender etc)
+  variant: string
+
+  // region from where the person, animal or entity is coming from (human, mechanical, alien planet, european, south-american etc)
+  region: string
+
+  // identity picture
+  identityImage: string
+
+  // identity voice
+  identityVoice: string
+}

packages/client/src/index.ts

@@ -0,0 +1,28 @@
+
+export {
+  createClap,
+  editClapDialogues,
+  editClapEntities,
+  editClapMusic,
+  editClapSounds,
+  editClapStory,
+  editClapStoryboards,
+  editClapVideos,
+  exportClapToVideo,
+} from './api'
+
+export {
+  defaultAitubeHostname,
+  defaultClapWidth,
+  defaultClapHeight,
+  defaultExportFormat,
+  aitubeUrl,
+  aitubeApiVersion,
+  aitubeApiUrl,
+  ClapEntityPrompt,
+  SupportedExportFormat
+} from "./constants"
+
+export {
+  applyClapCompletion,
+} from "./utils"

packages/client/src/parsers/index.ts

@@ -0,0 +1,3 @@
+export { parseEntityPrompt } from "./parseEntityPrompt"
+export { parseString } from "./parseString"
+export { parseStringArray } from "./parseStringArray"

packages/client/src/parsers/parseEntityPrompt.ts

@@ -0,0 +1,30 @@
+
+
+import { ClapEntityPrompt } from "@/constants/types"
+
+import { parseString } from "./parseString"
+import { ClapSegmentCategory } from "@aitube/clap"
+
+export function parseEntityPrompt(entityPrompt: Partial<ClapEntityPrompt> = {}): ClapEntityPrompt {
+
+  return {
+    name: parseString(entityPrompt?.name),
+
+    category: parseString(entityPrompt?.category) as ClapSegmentCategory,
+
+    // age of the person, animal or entity (eg. robot, talking spaceship etc)
+    age: parseString(entityPrompt?.age),
+
+    // characterization of the person, animal or entity (texture, hair color, gender etc)
+    variant: parseString(entityPrompt?.variant),
+
+    // region from where the person, animal or entity is coming from (human, mechanical, alien planet, european, south-american etc)
+    region: parseString(entityPrompt?.region),
+
+    // identity picture
+    identityImage: parseString(entityPrompt?.identityImage),
+
+    // identity voice
+    identityVoice: parseString(entityPrompt?.identityVoice),
+  }
+}

packages/client/src/parsers/parseString.ts

@@ -0,0 +1,7 @@
+export function parseString(input?: any, defaultValue?: string): string {
+  const defValue = `${defaultValue || ""}`
+
+  if (typeof input !== "string") { return defValue }
+  
+  return input || defValue
+}

packages/client/src/parsers/parseStringArray.ts

@@ -0,0 +1,9 @@
+export function parseStringArray(something: any): string[] {
+  let result: string[] = []
+  if (typeof something === "string") {
+    result = [something]
+  } else if (Array.isArray(something)) {
+    result = something.map(thing => typeof thing === "string" ? thing : "").filter(x => x)
+  }
+  return result
+}

packages/client/src/utils/applyClapCompletion.ts

@@ -0,0 +1,21 @@
+import { ClapCompletionMode, ClapProject, updateClap } from "@aitube/clap"
+
+export async function applyClapCompletion(
+  existingClap: ClapProject,
+  newerClap: ClapProject,
+  clapCompletionMode: ClapCompletionMode
+): Promise<ClapProject> {
+  // in both those mode we leave full control to what is inside "newerClap"
+  if (clapCompletionMode === ClapCompletionMode.FULL || clapCompletionMode === ClapCompletionMode.PARTIAL) {
+    return newerClap
+  }
+
+  // else we are in ClapCompletionMode.MERGE or ClapCompletionMode.REPLACE
+  const result = await updateClap(existingClap, newerClap, {
+    // the newer clap meta may contain incomplete information
+    overwriteMeta: false,
+    inlineReplace: clapCompletionMode === ClapCompletionMode.REPLACE
+  })
+
+  return result
+}

packages/client/src/utils/index.ts

@@ -0,0 +1 @@
+export { applyClapCompletion } from "./applyClapCompletion"

packages/client/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": "./",
+    "paths": { 
+      "@/*": ["src/*"]
+    },
+    "lib": ["ESNext", "DOM"],
+    "module": "esnext",
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "composite": true,
+    "strict": true,
+    "downlevelIteration": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowJs": true,
+    "types": [
+      "bun-types"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

packages/client/tsconfig.types.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}