scrolltube 2.1.2 → 2.1.4

package/dist/pipeline/index.js

@@ -32,9 +32,13 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssetPipeline = void 0;
 const cloud_service_1 = require("./cloud-service");
+const chalk_1 = __importDefault(require("chalk"));
 class AssetPipeline {
     driver;
     options;
@@ -88,11 +92,76 @@ class AssetPipeline {
         const tempDir = this.driver.join(outDir, '.temp-frames');
         const framesDir = this.driver.join(tempDir, 'frames');
         const depthsDir = this.driver.join(tempDir, 'depths');
+        // Inform users of agents using this command, that this may take a few minutes to complete. 
+        console.log(chalk_1.default.yellow('\n⚠️  This may take a few minutes to complete.\n'));
         this.report('initializing', 0, `Creating project: ${name}`);
         await this.driver.mkdir(outDir);
         await this.driver.mkdir(tempDir);
         await this.driver.mkdir(framesDir);
         await this.driver.mkdir(depthsDir);
+        // 0. PRE-FLIGHT: DIMENSIONS & VARIANT FILTERING
+        this.report('initializing', 5, 'Detecting source dimensions...');
+        let sourceDimensions = { width: 1920, height: 1080 }; // Default fallback
+        try {
+            sourceDimensions = await this.driver.getVideoDimensions(input);
+            console.log(chalk_1.default.cyan(`🎞️  Source Resolution: ${sourceDimensions.width}x${sourceDimensions.height}`));
+        }
+        catch (e) {
+            console.warn(chalk_1.default.yellow(`⚠️  Could not detect source dimensions. Proceeding with defaults.`));
+        }
+        const requestedVariants = this.normalizeVariants(opts.variants);
+        const validVariants = requestedVariants.filter(v => {
+            const isTooLarge = v.width > sourceDimensions.width || v.height > sourceDimensions.height;
+            if (isTooLarge) {
+                console.warn(chalk_1.default.yellow(`⚠️  Skipping variant ${v.id} (${v.width}x${v.height}) as it exceeds source resolution. (Upscaling is disabled)`));
+                return false;
+            }
+            return true;
+        });
+        if (validVariants.length === 0 && requestedVariants.length > 0) {
+            console.warn(chalk_1.default.bold.red(`\n❌ All requested variants were too large for the source video!`));
+            console.log(chalk_1.default.white(`Hint: Upscale your video first, or request smaller variants.\n`));
+            // Re-add at least one matching the source? No, let's let the user decide or use a safe fallback.
+            // For now, let's use the source resolution as a single variant if everything else failed.
+            const sourceVariant = {
+                id: 'source-res',
+                width: sourceDimensions.width,
+                height: sourceDimensions.height,
+                orientation: sourceDimensions.width > sourceDimensions.height ? 'landscape' : 'portrait',
+                aspectRatio: `${sourceDimensions.width}:${sourceDimensions.height}`,
+                media: '(min-width: 0px)'
+            };
+            validVariants.push(sourceVariant);
+            console.log(chalk_1.default.blue(`ℹ️  Falling back to source resolution variant: ${sourceDimensions.width}x${sourceDimensions.height}`));
+        }
+        // 0. SAVE SOURCE (Copy input video to the project directory)
+        let sourceRelPath = '';
+        try {
+            let sourceFileName = 'video-source';
+            let extension = '.mp4';
+            if (typeof input === 'string') {
+                const parts = input.split('.');
+                if (parts.length > 1)
+                    extension = `.${parts.pop()}`;
+                sourceFileName += extension;
+                await this.driver.copyFile(input, this.driver.join(outDir, sourceFileName));
+                sourceRelPath = `./${sourceFileName}`;
+            }
+            else if (input && input.arrayBuffer) {
+                // Handle File/Blob (Browser)
+                const fileName = input.name || 'source.mp4';
+                const parts = fileName.split('.');
+                if (parts.length > 1)
+                    extension = `.${parts.pop()}`;
+                sourceFileName += extension;
+                const buffer = await input.arrayBuffer();
+                await this.driver.writeFile(this.driver.join(outDir, sourceFileName), new Uint8Array(buffer));
+                sourceRelPath = `./${sourceFileName}`;
+            }
+        }
+        catch (e) {
+            console.warn(chalk_1.default.yellow(`⚠️  Could not save a local copy of source video: ${e instanceof Error ? e.message : String(e)}`));
+        }
         // 1. FRAME EXTRACTION
         this.report('extracting', 10, 'Extracting frames from source...');
         await this.driver.extractFrames(input, framesDir);
@@ -127,12 +196,12 @@ class AssetPipeline {
         const variants = await this.processVariants(tempDir, trackingData, {
             step,
             depth: isDepthActive,
-            variants: this.normalizeVariants(opts.variants),
+            variants: validVariants,
             outDir
         });
         // 4. SAVE CONFIG
         this.report('saving', 90, 'Finalizing project configuration...');
-        const config = await this.saveConfig(variants, outDir);
+        const config = await this.saveConfig(variants, outDir, sourceRelPath);
         // Cleanup
         await this.driver.remove(tempDir);
         this.report('saving', 100, 'Project ready!');
@@ -206,7 +275,7 @@ class AssetPipeline {
         }
         return assetVariants;
     }
-    async saveConfig(variants, outDir) {
+    async saveConfig(variants, outDir, sourcePath) {
         const pkg = require('../../package.json');
         const config = {
             version: pkg.version,
@@ -216,10 +285,13 @@ class AssetPipeline {
                 totalDuration: "300vh",
                 scenes: [{
                         id: "scene-1", assetId: "main-sequence", startProgress: 0, duration: 1,
-                        assetRange: [0, variants[0].frameCount - 1], layers: []
+                        assetRange: [0, (variants.length > 0 ? variants[0].frameCount : 1) - 1], layers: []
                     }]
             }
         };
+        if (sourcePath) {
+            config.source = sourcePath;
+        }
         await this.driver.writeFile(this.driver.join(outDir, 'scrolltube.json'), JSON.stringify(config, null, 2));
         return config;
     }

package/dist/pipeline/node-driver.d.ts

@@ -8,8 +8,14 @@ export declare class NodeDriver implements IPipelineDriver {
     exists(filePath: string): Promise<boolean>;
     readdir(dirPath: string): Promise<string[]>;
     remove(filePath: string): Promise<void>;
+    copyFile(src: string, dest: string): Promise<void>;
     join(...parts: string[]): string;
     resolve(...parts: string[]): string;
+    getVideoDimensions(input: string): Promise<{
+        width: number;
+        height: number;
+    }>;
+    private parseDimensions;
     extractFrames(videoSource: string, outputDir: string, onProgress?: (percent: number) => void): Promise<void>;
     processImage(input: Uint8Array | string, config: VariantConfig, options?: {
         grayscale?: boolean;

package/dist/pipeline/node-driver.js

@@ -70,19 +70,45 @@ class NodeDriver {
     async remove(filePath) {
         await fs.remove(filePath);
     }
+    async copyFile(src, dest) {
+        await fs.copy(src, dest);
+    }
     join(...parts) {
         return path.join(...parts);
     }
     resolve(...parts) {
         return path.resolve(...parts);
     }
+    async getVideoDimensions(input) {
+        return new Promise((resolve, reject) => {
+            try {
+                const result = (0, child_process_1.execSync)(`"${this.ffmpegPath}" -i "${input}"`, { stdio: 'pipe' }).toString();
+                // ffmpeg outputs info to stderr, which execSync might throw on if -i is used without an output file
+                this.parseDimensions(result, resolve, reject);
+            }
+            catch (err) {
+                // execSync throws if exit code != 0, but ffmpeg -i returns 1 because no output file 
+                const output = err.stderr ? err.stderr.toString() : (err.stdout ? err.stdout.toString() : '');
+                this.parseDimensions(output, resolve, reject);
+            }
+        });
+    }
+    parseDimensions(output, resolve, reject) {
+        const match = output.match(/, (\d{2,5})x(\d{2,5})/);
+        if (match) {
+            resolve({ width: parseInt(match[1]), height: parseInt(match[2]) });
+        }
+        else {
+            reject(new Error('Could not parse video dimensions.'));
+        }
+    }
     async extractFrames(videoSource, outputDir, onProgress) {
         return new Promise((resolve, reject) => {
             // For simplicity, we use execSync in a promise or spawn for progress
             try {
                 // ffmpeg -i input output%04d.png
                 // For now, let's keep it simple like existing CLI
-                (0, child_process_1.execSync)(`"${this.ffmpegPath}" -i "${videoSource}" "${outputDir}/frame_%04d.png"`, { stdio: 'inherit' });
+                (0, child_process_1.execSync)(`"${this.ffmpegPath}" -hide_banner -loglevel error -i "${videoSource}" "${outputDir}/frame_%04d.png"`, { stdio: 'inherit' });
                 resolve();
             }
             catch (err) {

package/dist/pipeline/types.d.ts

@@ -18,8 +18,13 @@ export interface IPipelineDriver {
     exists(path: string): Promise<boolean>;
     readdir(path: string): Promise<string[]>;
     remove(path: string): Promise<void>;
+    copyFile(src: string, dest: string): Promise<void>;
     join(...parts: string[]): string;
     resolve(...parts: string[]): string;
+    getVideoDimensions(input: string | File | Blob): Promise<{
+        width: number;
+        height: number;
+    }>;
     extractFrames(videoSource: string | File | Blob, outputDir: string, onProgress?: (percent: number) => void): Promise<void>;
     processImage(input: Uint8Array | string, config: VariantConfig, options: {
         grayscale?: boolean;

package/docs/ai-integration.md

@@ -10,9 +10,10 @@ For an AI to successfully build an experience, it must follow these two phases:
 The agent should first use the CLI to process raw media into an intelligent ScrollTube project.
 ```bash
 # Example: Process a video with AI tracking and depth maps
-npx stube create input.mp4 --name "my-project" --track "main product" --cloud --depth
+npx scrolltube create input.mp4 --name "my-project" --track "main product" --cloud --depth
+
 ```
-**Output:** A directory containing optimized frames, depth maps, and a `scrolltube.json` file.
+**Output:** A directory containing optimized frames, depth maps in variants for specific resolutions and a `scrolltube.json` file and a copy of the source - raw media.
 
 ### Phase B: Immersive Implementation (React)
 The agent then uses the generated JSON to build the UI components.
@@ -30,7 +31,7 @@ export const MyExperience = () => (
         {/* Pins content to the tracked subject automatically */}
         <SubjectLayer offset={{ x: 10, y: -5 }}>
           <div className="info-box">
-             Premium Tubesmanship
+            Hello From ScrollTube
           </div>
         </SubjectLayer>
       </div>
@@ -47,7 +48,8 @@ Paste this into your chat to turn an AI into a ScrollTube specialist:
 You are the ScrollTube Implementation Specialist. Your goal is to design immersive scroll experiences.
 
 Workflow:
-1. CLI FIRST: Start by suggesting `npx stube create` to process assets.
+1. CLI FIRST: Start by suggesting `npx scrolltube create` to process assets.
+
 2. ENGINE AWARE: Use 'ScrollTubeProvider' to sync the engine with React state.
 3. SUBJECT PINS: Use 'SubjectLayer' to attach UI to the product coordinates found by the AI tracker.
 4. DYNAMIC UI: Use the 'progress' (0-1) or 'frame' count from 'useScrollTube' for custom triggers.
@@ -70,3 +72,9 @@ This workflow enables a powerful business model:
 3. **The AI Agent** uses that intelligence to write the perfectly synced creative layer.
 
 You provide the **SDK**, the AI provides the **Implementation**.
+yer.
+
+You provide the **SDK**, the AI provides the **Implementation**.
+yer.
+
+You provide the **SDK**, the AI provides the **Implementation**.

package/docs/architecture.md

@@ -15,6 +15,8 @@ The engine expects a `ProjectConfiguration` object (defined in `src/core/types.t
 - **`settings`**: Base resolutions, scroll modes, and base path.
 - **`assets`**: An array of `SequenceAsset` with multiple `variants` (Mobile vs Desktop).
 - **`timeline`**: A map of `scenes` and `layers`.
+- **`source`**: (New) Relative path to the original source video file, preserved for future edits or variant regenerations.
+
 
 ---
 

package/docs/asset-pipeline.md

@@ -18,12 +18,17 @@ This means you have a single source of truth for your processing logic, while be
 
 ## 2. CLI Usage
 
-The `npx stube create` command is the primary wrapper for the pipeline on your local machine.
+The `npx scrolltube create` command is the primary wrapper for the pipeline on your local machine.
+
  
  ```bash
- npx stube create <input> [options]
+ npx scrolltube create <input> [options]
  ```
  
+-> [!TIP]
+-> **Interactive Mode**: If you omit the input path or provide an invalid one, the CLI will now prompt you to try again instead of exiting.
+
+ 
  ### Options:
  - `-n, --name <string>`: Project folder name.
  - `-p, --track <text>`: Target object to track (e.g. "red car").
@@ -56,14 +61,16 @@ const zip = await pipeline.create({
 ```
 
 ### Core Pipeline Steps:
- 1.  **Auto-Upload**: If you provide a local `.mp4`, it's automatically uploaded to the cloud for processing.
- 2.  **Extraction**: Converts video files into high-quality image sequences.
+ 1.  **Source Preservation**: Automatically saves a copy of your original video as `video-source.[ext]` in the project directory for future-proofing.
+ 2.  **Extraction**: Converts video files into high-quality image sequences (with minimal terminal noise).
  3.  **AI Tracking**: Identifies the main subject (using **SAM 3**). Our engine now features **Sticky Tracking**—if the subject is obscured for a few frames, the coordinates hold their last known position.
- 4.  **Variant Generation**: 
+ 4.  **Upscale Protection**: Automatically detects source dimensions and filters out any requested variants that would require upscaling, ensuring maximum performance and visual quality.
+ 5.  **Variant Generation**: 
      - **Smart Crop**: Centers the images based on the tracked subject.
      - **Resolution Factory**: Creates Portrait (9:16) and Landscape (16:9) pairs for each target resolution (e.g. 720p, 1080p).
     - **Compression**: Optimized `.webp` generation via Sharp (Node) or Canvas (Browser).
- 5.  **Metadata Export**: Generates the final `scrolltube.json` with **root-relative paths** for easier deployment.
+ 6.  **Metadata Export**: Generates the final `scrolltube.json` with **root-relative paths** and source file references.
+
  
  ---
  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrolltube",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "ScrollTube is a web-based tool for scroll-triggered animations.",
   "main": "dist/core/scrolltube.umd.min.js",
   "module": "dist/core/scrolltube.umd.min.js",
@@ -23,7 +23,7 @@
   },
   "types": "dist/core/index.d.ts",
   "bin": {
-    "stube": "dist/cli/index.js"
+    "scrolltube": "dist/cli/index.js"
   },
   "files": [
     "dist",