@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/import-media/file-format-support.md

@@ -1,24 +1,24 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Import Media Assets](./import-media.md) > [File Format Support](./import-media/file-format-support.md)
 
 ---
 
-When building creative applications with CE.SDK, understanding which file formats your users can import is crucial for delivering a smooth editing experience. CE.SDK supports a comprehensive range of modern media formats.
+When building server-side creative applications with CE.SDK in Node.js, understanding which file formats you can import is essential for processing user content at scale. CE.SDK's Node.js package supports the same comprehensive range of modern media formats as the browser version.
 
-This guide provides a complete reference of supported file formats for importing media, templates, and fonts into CE.SDK on web platforms.
+This guide provides a complete reference of supported file formats for importing media, templates, and fonts into CE.SDK on Node.js.
 
 ## Supported Import Formats
 
-CE.SDK supports importing the following media types directly in the browser:
+CE.SDK for Node.js supports importing the following media types:
 
-| Category      | Supported Formats                                                                       |
-| ------------- | --------------------------------------------------------------------------------------- |
-| **Images**    | `.png`, `.jpeg`, `.jpg`, `.gif`, `.webp`, `.svg`, `.bmp`                                |
-| **Video**     | `.mp4` (H.264/AVC, H.265/HEVC), `.mov` (H.264/AVC, H.265/HEVC), `.webm` (VP8, VP9, AV1) |
-| **Audio**     | `.mp3`, `.m4a`, `.mp4` (AAC or MP3), `.mov` (AAC or MP3)                                |
-| **Animation** | `.json` (Lottie)                                                                        |
-| **Templates** | `.idml` (InDesign), `.psd` (Photoshop), `.scene` (CE.SDK Native)                        |
+| Category        | Supported Formats                                                                       |
+| --------------- | --------------------------------------------------------------------------------------- |
+| **Images**      | `.png`, `.apng`, `.jpeg`, `.jpg`, `.gif`, `.webp`, `.svg`, `.bmp`                       |
+| **Video**       | `.mp4` (H.264/AVC, H.265/HEVC), `.mov` (H.264/AVC, H.265/HEVC), `.webm` (VP8, VP9, AV1) |
+| **Audio**       | `.mp3`, `.m4a`, `.mp4` (AAC or MP3), `.mov` (AAC or MP3)                               |
+| **Animation**   | `.json` (Lottie)                                                                        |
+| **Templates**   | `.idml` (InDesign), `.psd` (Photoshop), `.scene` (CE.SDK Native)                       |
 
 > **Note:** Need to import a format not listed here? CE.SDK allows you to create custom
 > importers for any file type by using our Scene and Block APIs
@@ -27,50 +27,51 @@ CE.SDK supports importing the following media types directly in the browser:
 
 ## Video and Audio Codecs
 
-While container formats (`.mp4`, `.mov`, `.webm`) define how media is packaged, codecs determine how the content is compressed. CE.SDK supports the following codecs for web playback and editing:
+While container formats (`.mp4`, `.mov`, `.webm`) define how media is packaged, codecs determine how the content is compressed. CE.SDK for Node.js supports the following codecs:
 
 ### Video Codecs
 
-- **H.264 / AVC** (in `.mp4` or `.mov`) – Universally supported across all modern browsers
-- **H.265 / HEVC** (in `.mp4` or `.mov`) – Requires platform-specific support; availability varies by browser and operating system
-- **VP8, VP9, AV1** (in `.webm`) – Modern web-native codecs with broad browser support
+- **H.264 / AVC** (in `.mp4` or `.mov`) – Universally supported with software decoding
+- **H.265 / HEVC** (in `.mp4` or `.mov`) – Requires platform-specific support; availability varies by system libraries
+- **VP8, VP9, AV1** (in `.webm`) – Modern codecs supported through system media libraries
 
 ### Audio Codecs
 
 - **MP3** (in `.mp3` files or within `.mp4`/`.mov` containers)
 - **AAC** (in `.m4a`, `.mp4`, or `.mov` containers)
 
-> **Warning:** H.265/HEVC support varies by browser and requires hardware acceleration or
-> licensed software decoders. Always test video playback on your target browsers
-> before deploying H.265 content to end users.
+> **Note:** In Node.js environments, video and audio codec support depends on the system's
+> installed media libraries and codecs. Ensure your deployment environment has
+> the necessary codecs installed for your target formats.
 
 ## Size Limits and Constraints
 
-CE.SDK processes all media client-side in the browser, which means performance is bounded by the user's hardware capabilities. Here are the practical limits to keep in mind:
+CE.SDK for Node.js processes media using the system's available resources. Server environments typically have more memory and CPU resources than browsers, but you should still be mindful of limits:
 
 ### Image Resolution Limits
 
 | Constraint            | Recommendation / Limit                                                                                                                                                                                                |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Input Resolution**  | Maximum input resolution is **4096×4096 pixels**. Images from external sources (e.g., Unsplash) are resized to this size before rendering on the canvas. You can modify this value using the `maxImageSize` setting.  |
-| **Output Resolution** | There is no enforced output resolution limit. Theoretically, the editor supports output sizes up to **16,384×16,384 pixels**. However, practical limits depend on the device's GPU capabilities and available memory. |
+| **Input Resolution**  | Maximum input resolution is **4096×4096 pixels** by default. Images from external sources are resized to this size before rendering. You can modify this value using the `maxImageSize` setting.  |
+| **Output Resolution** | There is no enforced output resolution limit. The editor theoretically supports output sizes up to **16,384×16,384 pixels**. Practical limits depend on available system memory and CPU resources. |
 
-All image processing in CE.SDK is handled client-side, so these values depend on the **maximum texture size** supported by the user's hardware. The default limit of 4096×4096 is a safe baseline that works universally. Higher resolutions (e.g., 8192×8192) may work on certain devices but could fail on others during export if the GPU texture size is exceeded.
+All image processing in CE.SDK for Node.js is handled server-side using CPU-based rendering (no GPU required). The default limit of 4096×4096 ensures reasonable processing times and memory usage. Higher resolutions will work but may require more memory and longer processing times.
 
-> **Note:** To ensure consistent results across devices, test higher output sizes on your
-> target hardware and set conservative defaults in production.
+> **Note:** For server deployments, monitor memory usage when processing high-resolution
+> images. Consider implementing request queuing or resource pooling for
+> production workloads.
 
 ### Video Resolution and Duration Limits
 
 | Constraint     | Recommendation / Limit                                                                                                                                                                                                                                                                                                         |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Resolution** | Up to **4K UHD** is supported for **playback** and **export**, depending on the user's hardware and available GPU resources. For **import**, CE.SDK does not impose artificial limits, but maximum video size is bounded by the **32-bit address space of WebAssembly (wasm32)** and the **browser tab's memory cap (~2 GB)**. |
-| **Frame Rate** | 30 FPS at 1080p is broadly supported; 60 FPS and high-res exports benefit from hardware acceleration                                                                                                                                                                                                                           |
-| **Duration**   | Stories and reels of up to **2 minutes** are fully supported. Longer videos are also supported, but we generally found a maximum duration of **10 minutes** to be a good balance for a smooth editing experience and a pleasant export duration of around one minute on modern hardware.                                       |
+| **Resolution** | Up to **4K UHD** is supported for processing, depending on available system resources. Maximum video size is bounded by the **32-bit address space of WebAssembly (wasm32)** and **available system memory**. |
+| **Frame Rate** | 30 FPS at 1080p is recommended; 60 FPS works but increases processing time                                                                                                                                           |
+| **Duration**   | Stories and reels of up to **2 minutes** process efficiently. Longer videos up to **10 minutes** are supported, with processing time scaling proportionally with duration.                                       |
 
-> **Note:** Performance scales with client hardware. For best results with high-resolution
-> or high-frame-rate video, modern CPUs/GPUs with hardware acceleration are
-> recommended.
+> **Warning:** Server-side video processing is CPU-intensive. For production deployments,
+> consider implementing job queues, progress tracking, and timeout handling for
+> long-running video operations.
 
 ## Format-Specific Considerations
 
@@ -100,19 +101,21 @@ The following SVG elements are not supported:
 - Some filter elements (`<feComponentTransfer>`, `<feConvolveMatrix>`, `<feTile>`, `<feDropShadow>`)
 - Inlined SVGs via `<image>` or `<feImage>` elements
 
-> **Note:** When preparing SVG assets, always export with "presentation attributes" and
-> convert text to paths for maximum compatibility with CE.SDK.
+> **Note:** When preparing SVG assets for server-side processing, always export with
+> "presentation attributes" and convert text to paths for maximum compatibility.
 
 ### WebP Support
 
-WebP images are fully supported for import. CE.SDK handles both lossy and lossless WebP formats, including images with transparency (alpha channel). WebP provides excellent compression with high quality, making it ideal for web-based creative applications.
+WebP images are fully supported for import in Node.js environments. CE.SDK handles both lossy and lossless WebP formats, including images with transparency (alpha channel). WebP provides excellent compression with high quality, making it ideal for optimizing storage and bandwidth in server applications.
 
-### Animated GIF Considerations
+### Animated Image Considerations (GIF and APNG)
 
-While CE.SDK can import animated GIF files, they are rendered as static images showing only the first frame. For animated content, consider using:
+CE.SDK handles animated GIF and APNG files based on scene type:
 
-- **Lottie animations** (`.json`) for vector-based animations
-- **Video files** (`.mp4`, `.webm`) for complex animated content
+- **Design scenes**: rendered as a static image showing the first frame.
+- **Video scenes**: imported as a looping video fill, with frame timing and duration parsed from the file's metadata.
+
+For complex animated content in server environments, prefer `.mp4`, which offers better compression and broader codec support. If you need to extract every frame from a GIF or APNG, process the file frame-by-frame outside of CE.SDK.
 
 ### Template Format Details
 
@@ -120,13 +123,13 @@ CE.SDK supports importing templates from popular design applications:
 
 - **IDML** (InDesign Markup Language) – Import layouts and designs created in Adobe InDesign
 - **PSD** (Photoshop Document) – Import layered Photoshop files with preserved layer structure
-- **SCENE** – CE.SDK's native scene format, optimized for fast loading and editing
+- **SCENE** – CE.SDK's native scene format, optimized for fast loading and processing
 
-When importing IDML or PSD files, CE.SDK preserves layer hierarchy, text formatting, and design structure where possible. Some advanced effects or features specific to the source application may require manual adjustment after import.
+When importing IDML or PSD files in Node.js, CE.SDK preserves layer hierarchy, text formatting, and design structure where possible. Some advanced effects or features specific to the source application may require manual adjustment after import.
 
 ## Font Format Support
 
-CE.SDK supports modern web font formats for typography:
+CE.SDK for Node.js supports modern font formats for typography:
 
 | Format   | Description                       |
 | -------- | --------------------------------- |
@@ -136,43 +139,57 @@ CE.SDK supports modern web font formats for typography:
 | `.woff2` | Compressed Web Open Font Format 2 |
 
 > **Warning:** Ensure fonts are appropriately licensed before embedding them in your
-> application. Many commercial fonts have specific licensing requirements for
-> web use and redistribution.
+> server-side application. Many commercial fonts have specific licensing
+> requirements for server use and programmatic rendering.
 
-## Best Practices
+## Best Practices for Node.js
 
 ### Format Selection
 
-When building your application, consider these format recommendations:
+When building server-side applications, consider these format recommendations:
 
-- **Images**: Use `.webp` for the best compression-to-quality ratio on the web. Fall back to `.png` for transparency or `.jpeg` for photographs without transparency.
-- **Video**: Prefer `.mp4` with H.264 encoding for maximum browser compatibility. Use `.webm` for modern browsers when you need open-source codecs.
+- **Images**: Use `.webp` for optimal storage efficiency. Use `.png` for lossless images with transparency or `.jpeg` for photographs.
+- **Video**: Prefer `.mp4` with H.264 encoding for maximum compatibility across deployment environments.
 - **Audio**: Use `.mp3` for universal compatibility or `.m4a` (AAC) for better quality at smaller file sizes.
-- **Templates**: Use `.scene` format for CE.SDK-to-CE.SDK workflows, or import from `.psd`/`.idml` when migrating content from design tools.
+- **Templates**: Use `.scene` format for CE.SDK-to-CE.SDK workflows to minimize parsing overhead.
 
 ### Validation and Error Handling
 
-Always validate file formats before attempting import:
+Always validate file formats before processing on the server:
+
+1. **Check file signatures (magic bytes)** not just extensions – users may upload misnamed files
+2. **Validate MIME types** from uploaded content
+3. **Set maximum file size limits** to prevent resource exhaustion
+4. **Implement timeouts** for processing operations to prevent hanging requests
+5. **Log validation failures** for debugging and security monitoring
+
+### Resource Management
+
+For production Node.js deployments, implement proper resource management:
+
+- **Memory limits**: Monitor and limit memory per process (use Node.js `--max-old-space-size` flag)
+- **Concurrency control**: Limit concurrent processing jobs to prevent resource exhaustion
+- **Cleanup**: Always dispose of resources after processing (call `dispose()` on engine instances)
+- **Queue systems**: Use job queues (Bull, BullMQ) for long-running video processing tasks
+- **Progress tracking**: Implement progress callbacks for long operations
+- **Caching**: Cache processed assets when appropriate to reduce redundant processing
+
+### File System Considerations
 
-1. **Check MIME types** on file upload to quickly reject unsupported formats
-2. **Validate file extensions** as a first line of defense
-3. **Monitor file sizes** to prevent memory issues with extremely large files
-4. **Provide clear error messages** to users when imports fail, explaining which formats are supported
+When working with local files in Node.js:
 
-### Memory Management
+- Use absolute paths or resolve paths relative to your application root
+- Clean up temporary files after processing
+- Consider streaming large files instead of loading them entirely into memory
+- Handle file permissions correctly for both reading source files and writing exports
 
-For web applications, be mindful of browser memory constraints:
 
-- Large video files (>100 MB) may cause performance issues or browser tab crashes
-- Multiple high-resolution images loaded simultaneously can exhaust GPU memory
-- Consider implementing lazy loading for asset libraries with many files
-- Provide progress indicators for large file imports to improve user experience
 
 ---
 
 ## More Resources
 
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Node.js Documentation Index](https://img.ly/docs/cesdk/node.md)** - Browse all Node.js documentation
 - **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
-- **[Web Documentation](./js.md)** - Interactive documentation with examples
-- **[Support](mailto:support@img.ly)** - Contact IMG.LY support
+- **[Web Documentation](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support