apexify.js 5.0.3 → 5.1.0

package/README.md

@@ -4,18 +4,153 @@
 
 ![ApexPainter Banner](https://imgur.com/0E9GTmP)
 
-**The Ultimate TypeScript Canvas Library for Node.js**
+**🚀 One Library. Infinite Possibilities. Professional Results.**
 
 [![npm version](https://badge.fury.io/js/apexify.js.svg)](https://badge.fury.io/js/apexify.js)
 [![npm downloads](https://img.shields.io/npm/dt/apexify.js.svg)](https://www.npmjs.com/package/apexify.js)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-Compatible-black?logo=next.js)](https://nextjs.org/)
+[![Discord](https://img.shields.io/badge/Discord-Bot%20Ready-7289DA?logo=discord)](https://discord.com/)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-*Create stunning visuals with professional-grade canvas rendering, image processing, and text effects*
+**The most powerful, versatile canvas rendering library for Node.js, Next.js, Discord bots, and beyond.**
+
+*Create stunning visuals, generate images on-the-fly, build design tools, and power your applications with professional-grade canvas rendering and image processing.*
 
 </div>
 
+## 🌟 Why ApexPainter?
+
+**ApexPainter is not just another canvas library** - it's a complete visual creation toolkit that works everywhere:
+
+- ✅ **Next.js** - Perfect for both frontend and backend image generation
+- ✅ **Discord Bots** - Create dynamic images, welcome cards, level-up cards, and more
+- ✅ **Server-Side Rendering** - Generate images in API routes, server actions, and edge functions
+- ✅ **Design Tools** - Build Photoshop-like applications with code export capabilities
+- ✅ **Web Applications** - Power your websites with dynamic image generation
+- ✅ **Automation** - Batch process images, create thumbnails, generate social media assets
+- ✅ **E-commerce** - Generate product images, banners, and marketing materials
+- ✅ **Social Media** - Create profile pictures, cover images, and post graphics
+- ✅ **Gaming** - Generate game assets, UI elements, and character cards
+- ✅ **Business** - Create business cards, certificates, and professional documents
+
+**One library. Every use case. Zero compromises.**
+
+---
+
+## 🎯 Perfect For
+
+### 🚀 **Next.js Applications**
+Generate images in your Next.js app - both client and server-side. Perfect for:
+- **API Routes**: Generate images on-demand via API endpoints
+- **Server Actions**: Create images in server-side functions
+- **Static Generation**: Pre-generate images at build time
+- **Edge Functions**: Lightweight image generation at the edge
+- **ISR (Incremental Static Regeneration)**: Update images dynamically
+
+```typescript
+// Next.js API Route Example
+// app/api/generate-image/route.ts
+import { ApexPainter } from 'apexify.js';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const painter = new ApexPainter();
+  const canvas = await painter.createCanvas({
+    width: 1200,
+    height: 630,
+    gradientBg: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#667EEA' },
+        { stop: 1, color: '#764BA2' }
+      ]
+    }
+  });
+  return new NextResponse(canvas.buffer, {
+    headers: { 'Content-Type': 'image/png' }
+  });
+}
+```
+
+### 🤖 **Discord Bots**
+Create stunning visuals for your Discord bot:
+- **Welcome Cards**: Personalized welcome images for new members
+- **Level-Up Cards**: Celebrate user achievements with custom graphics
+- **Profile Cards**: Generate user profile images with stats
+- **Leaderboards**: Visual leaderboard images
+- **Custom Commands**: Generate images on-demand via slash commands
+- **Event Graphics**: Create event banners and announcements
+
+```typescript
+// Discord Bot Example (discord.js)
+import { ApexPainter } from 'apexify.js';
+import { AttachmentBuilder } from 'discord.js';
+
+const painter = new ApexPainter();
+const canvas = await painter.createCanvas({
+  width: 800,
+  height: 400,
+  customBg: { source: userAvatar },
+  // Add welcome text, decorations, etc.
+});
+
+const attachment = new AttachmentBuilder(canvas.buffer, { name: 'welcome.png' });
+await channel.send({ files: [attachment] });
+```
+
+### 🎨 **Design Tools & Photoshop-Like Apps**
+Build powerful design applications:
+- **Visual Design Editors**: Create drag-and-drop design tools
+- **Code Export**: Convert visual designs into ApexPainter code
+- **Template Systems**: Pre-built templates for common designs
+- **Layer Management**: Complex compositions with multiple layers
+- **Export Options**: Multiple formats (PNG, JPEG, WebP, AVIF)
+- **Batch Processing**: Process multiple designs at once
+
+```typescript
+// Design Tool with Code Export
+const design = {
+  canvas: { width: 1920, height: 1080, colorBg: '#ffffff' },
+  elements: [
+    { type: 'shape', source: 'rectangle', x: 100, y: 100, /* ... */ },
+    { type: 'text', text: 'Hello World', x: 200, y: 200, /* ... */ }
+  ]
+};
+
+// Generate code from design
+const code = generateApexPainterCode(design);
+// Export as: await painter.createCanvas(...)
+```
+
+### 🌐 **Web Applications**
+Power your websites with dynamic image generation:
+- **OG Images**: Generate Open Graph images for social sharing
+- **Thumbnails**: Auto-generate thumbnails for content
+- **Banners**: Create dynamic banners and headers
+- **User Avatars**: Generate custom avatars with initials
+- **Charts & Graphs**: Visualize data with beautiful charts
+- **QR Codes**: Generate QR codes with custom styling
+
+### 📱 **Social Media & Marketing**
+Create professional marketing materials:
+- **Social Media Posts**: Generate posts for Instagram, Twitter, Facebook
+- **Story Graphics**: Create engaging story images
+- **Banner Ads**: Design eye-catching banner advertisements
+- **Email Graphics**: Generate images for email campaigns
+- **Product Images**: Create product showcases and catalogs
+
+### 🎮 **Gaming Applications**
+Generate game assets and UI elements:
+- **Character Cards**: Create character profile cards
+- **Achievement Badges**: Design achievement and trophy graphics
+- **Game UI**: Generate UI elements and HUD components
+- **Loading Screens**: Create dynamic loading screen graphics
+- **Leaderboards**: Visual leaderboard displays
+
+---
+
 ## ✨ Features Overview
 
 ### 🖼️ **Advanced Image Processing**
@@ -67,6 +202,35 @@
 - **Chain Operations**: Chain operations sequentially for complex workflows
 - **Advanced File Saving**: Save buffers to local files with smart naming, format conversion, and batch support
 
+### 🎬 **Comprehensive Video Processing** (v5.2.0+)
+- **Frame Extraction**: Extract single frames, multiple frames, or all frames from videos
+- **Video Information**: Get video metadata (duration, resolution, FPS, bitrate, codec)
+- **Thumbnail Generation**: Create grid thumbnails with multiple frames
+- **Format Conversion**: Convert videos between MP4, WebM, AVI, MOV, MKV
+- **Video Trimming**: Cut and trim video segments
+- **Audio Extraction**: Extract audio tracks (MP3, WAV, AAC, OGG)
+- **Watermarking**: Add image watermarks to videos with position and opacity control
+- **Speed Control**: Change video playback speed (slow motion, fast forward)
+- **Preview Generation**: Generate preview frames for video browsing
+- **Video Effects**: Apply filters (blur, brightness, contrast, saturation, grayscale, sepia, invert, sharpen, noise)
+- **Video Merging**: Concatenate videos sequentially, side-by-side, or in grids
+- **Rotation & Flipping**: Rotate videos (90°, 180°, 270°) and flip horizontally/vertically
+- **Video Cropping**: Crop videos to specific regions
+- **Compression**: Optimize video file sizes with quality presets
+- **Text Overlays**: Add text/subtitles to videos with positioning and timing
+- **Fade Effects**: Add fade in/out transitions
+- **Reverse Playback**: Reverse video and audio playback
+- **Video Loops**: Create seamless video loops
+- **Batch Processing**: Process multiple videos with different operations
+- **Scene Detection**: Automatically detect scene changes
+- **Video Stabilization**: Reduce camera shake and stabilize shaky footage
+- **Color Correction**: Professional color grading (brightness, contrast, saturation, hue, temperature)
+- **Picture-in-Picture**: Add overlay videos with position, size, and opacity control
+- **Split Screen**: Create side-by-side, top-bottom, or grid layouts with multiple videos
+- **Time-lapse Creation**: Speed up videos to create time-lapse effects
+- **Audio Control**: Mute videos or adjust audio volume
+- **Format Detection**: Analyze video codec, container, and properties
+
 ---
 
 ## 🚀 Quick Start
@@ -74,9 +238,35 @@
 ### Installation
 
 ```bash
-npm install apexify
+# npm
+npm install apexify.js
+
+# yarn
+yarn add apexify.js
+
+# pnpm
+pnpm add apexify.js
 ```
 
+### Platform Support
+
+✅ **Node.js** - Full support (v16+)  
+✅ **Next.js** - Frontend & Backend (App Router & Pages Router)  
+✅ **Discord.js** - Perfect for Discord bots  
+✅ **Express.js** - API endpoints and server-side rendering  
+✅ **Serverless** - AWS Lambda, Vercel, Netlify Functions  
+✅ **Docker** - Containerized applications  
+✅ **Edge Runtime** - Vercel Edge, Cloudflare Workers (with limitations)
+
+### Works Everywhere
+
+- 🖥️ **Server-Side**: Full feature support
+- 🌐 **API Routes**: Generate images on-demand
+- ⚡ **Edge Functions**: Lightweight image generation
+- 🤖 **Discord Bots**: Dynamic image creation
+- 🎨 **Design Tools**: Build visual editors
+- 📱 **Web Apps**: Client and server-side rendering
+
 ### Basic Usage
 
 ```typescript
@@ -630,19 +820,6 @@ const buttonText = await painter.createText({
 
 ## 📚 API Reference
 
-### Core Methods
-
-| Method | Description | Parameters |
-|--------|-------------|------------|
-| `createCanvas()` | Create a new canvas with background | `CanvasConfig` |
-| `createImage()` | Add shapes/images to canvas | `ImageProperties \| ImageProperties[]` |
-| `createText()` | Add text to canvas | `TextProperties \| TextProperties[]` |
-| `createChart()` | Generate charts | `ChartConfig` |
-| `createGIF()` | Create animated GIFs | `GIFConfig` |
-| `save()` | Save buffer to local file with advanced options | `Buffer, SaveOptions?` |
-| `saveMultiple()` | Save multiple buffers in batch | `Buffer[], SaveOptions?` |
-| `resetSaveCounter()` | Reset the save counter for naming | `void` |
-
 ### 🔄 **Flexible Parameters**
 
 Both `createImage()` and `createText()` methods accept:
@@ -680,9 +857,37 @@ This allows you to add multiple elements in one call for better performance and
 
 ---
 
-## 🆕 What's New in v4.9.30
-
-### 🎉 Major Feature Release
+## 🆕 What's New
+
+### 🎬 v5.2.0 - Comprehensive Video Processing Suite
+
+#### 18 New Video Features
+- 🎥 **Video Effects & Filters**: Apply professional filters (blur, brightness, contrast, saturation, grayscale, sepia, invert, sharpen, noise)
+- 🔗 **Video Merging**: Concatenate videos sequentially, side-by-side, or in grid layouts
+- 🔄 **Rotation & Flipping**: Rotate videos (90°, 180°, 270°) and flip horizontally/vertically
+- ✂️ **Video Cropping**: Crop videos to specific regions with precise control
+- 📦 **Video Compression**: Optimize video file sizes with quality presets and custom bitrate
+- 📝 **Text Overlays**: Add text/subtitles to videos with 7 position options and time-based visibility
+- 🌅 **Fade Effects**: Add fade in/out transitions at video start/end
+- ⏪ **Reverse Playback**: Reverse video and audio playback
+- 🔁 **Video Loops**: Create seamless video loops
+- ⚡ **Batch Processing**: Process multiple videos with different operations
+- 🎬 **Scene Detection**: Automatically detect scene changes with configurable threshold
+- 📹 **Video Stabilization**: Reduce camera shake and stabilize shaky footage
+- 🎨 **Color Correction**: Professional color grading (brightness, contrast, saturation, hue, temperature)
+- 📺 **Picture-in-Picture**: Add overlay videos with position, size, and opacity control
+- 🖼️ **Split Screen**: Create side-by-side, top-bottom, or grid layouts with multiple videos
+- ⏱️ **Time-lapse Creation**: Speed up videos to create time-lapse effects
+- 🔇 **Audio Control**: Mute videos or adjust audio volume
+- 🔍 **Format Detection**: Analyze video codec, container, and properties
+
+#### Enhanced Video Methods
+- ✅ **Smart Audio Detection**: Automatically detects if videos have audio streams
+- ✅ **Unified API**: All video features accessible through single `createVideo()` method
+- ✅ **Better Error Handling**: Clear error messages with FFmpeg installation guides
+- ✅ **Resource Management**: Automatic cleanup of temporary files
+
+### 🎉 v5.0.0 - Major Feature Release
 
 #### Background Enhancements
 - ✨ **Video Backgrounds**: Use video frames as dynamic backgrounds
@@ -717,6 +922,222 @@ See [CHANGELOG.md](CHANGELOG.md) for complete details.
 
 ---
 
+## 💼 Real-World Use Cases
+
+### 🎯 **Next.js Image Generation API**
+
+```typescript
+// app/api/og-image/route.ts
+import { ApexPainter } from 'apexify.js';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams;
+  const title = searchParams.get('title') || 'Default Title';
+  
+  const painter = new ApexPainter();
+  const canvas = await painter.createCanvas({
+    width: 1200,
+    height: 630,
+    gradientBg: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#667EEA' },
+        { stop: 1, color: '#764BA2' }
+      ]
+    }
+  });
+  
+  const image = await painter.createText({
+    text: title,
+    x: 600,
+    y: 315,
+    fontSize: 72,
+    bold: true,
+    color: '#FFFFFF',
+    textAlign: 'center'
+  }, canvas);
+  
+  return new NextResponse(image, {
+    headers: { 'Content-Type': 'image/png' }
+  });
+}
+```
+
+### 🤖 **Discord Bot Welcome Card**
+
+```typescript
+// discord-bot.ts
+import { ApexPainter } from 'apexify.js';
+import { Client, GatewayIntentBits, AttachmentBuilder } from 'discord.js';
+
+const client = new Client({ intents: [GatewayIntentBits.GuildMembers] });
+const painter = new ApexPainter();
+
+client.on('guildMemberAdd', async (member) => {
+  // Create welcome card
+  const canvas = await painter.createCanvas({
+    width: 1024,
+    height: 500,
+    customBg: { source: './assets/welcome-bg.jpg' }
+  });
+  
+  const image = await painter.createText([
+    {
+      text: `Welcome ${member.user.username}!`,
+      x: 512,
+      y: 200,
+      fontSize: 48,
+      bold: true,
+      color: '#FFFFFF',
+      textAlign: 'center'
+    },
+    {
+      text: `You are member #${member.guild.memberCount}`,
+      x: 512,
+      y: 280,
+      fontSize: 32,
+      color: '#CCCCCC',
+      textAlign: 'center'
+    }
+  ], canvas);
+  
+  const attachment = new AttachmentBuilder(image, { name: 'welcome.png' });
+  await member.guild.systemChannel?.send({ files: [attachment] });
+});
+```
+
+### 🎨 **Design Tool with Code Export**
+
+```typescript
+// design-editor.ts
+import { ApexPainter } from 'apexify.js';
+
+class DesignEditor {
+  private painter = new ApexPainter();
+  private design: any = { elements: [] };
+  
+  // Add element to design
+  addElement(element: any) {
+    this.design.elements.push(element);
+  }
+  
+  // Render design
+  async render() {
+    const canvas = await this.painter.createCanvas(this.design.canvas);
+    let buffer = canvas.buffer;
+    
+    for (const element of this.design.elements) {
+      if (element.type === 'shape') {
+        buffer = await this.painter.createImage(element, buffer);
+      } else if (element.type === 'text') {
+        buffer = await this.painter.createText(element, buffer);
+      }
+    }
+    
+    return buffer;
+  }
+  
+  // Export as ApexPainter code
+  exportCode() {
+    return `
+import { ApexPainter } from 'apexify.js';
+
+const painter = new ApexPainter();
+const canvas = await painter.createCanvas(${JSON.stringify(this.design.canvas, null, 2)});
+${this.design.elements.map((el: any, i: number) => 
+  `const step${i} = await painter.${el.type === 'shape' ? 'createImage' : 'createText'}(${JSON.stringify(el, null, 2)}, ${i === 0 ? 'canvas' : `step${i-1}`});`
+).join('\n')}
+    `.trim();
+  }
+}
+```
+
+### 📊 **Dynamic Chart Generation**
+
+```typescript
+// analytics-dashboard.ts
+import { ApexPainter } from 'apexify.js';
+
+async function generateAnalyticsChart(data: number[]) {
+  const painter = new ApexPainter();
+  
+  const chart = await painter.createChart({
+    chartType: 'bar',
+    chartNumber: 1,
+    data: {
+      chartData: { width: 800, height: 400 },
+      xLabels: data.map((_, i) => i),
+      yLabels: [0, 25, 50, 75, 100],
+      data: {
+        xAxis: data.map((value, i) => ({
+          label: `Day ${i + 1}`,
+          value,
+          position: { startsXLabel: i * 80, endsXLabel: (i + 1) * 80 }
+        })),
+        yAxis: data
+      }
+    }
+  });
+  
+  return chart;
+}
+```
+
+### 🖼️ **Batch Image Processing**
+
+```typescript
+// image-processor.ts
+import { ApexPainter } from 'apexify.js';
+
+async function processUserUploads(images: string[]) {
+  const painter = new ApexPainter();
+  
+  // Process all images in parallel
+  const results = await painter.batch(
+    images.map(image => ({
+      type: 'image' as const,
+      config: {
+        source: image,
+        x: 0,
+        y: 0,
+        filters: [{ type: 'gaussianBlur', radius: 5 }],
+        borderRadius: 20
+      }
+    }))
+  );
+  
+  // Save all processed images
+  await painter.saveMultiple(results, {
+    directory: './processed',
+    prefix: 'processed-',
+    naming: 'counter'
+  });
+  
+  return results;
+}
+```
+
+---
+
+## 🎓 Learning Resources
+
+### 📺 **Video Tutorials**
+Comprehensive video series covering:
+- Getting started with ApexPainter
+- Next.js integration
+- Discord bot development
+- Building design tools
+- Advanced features and techniques
+
+### 📚 **Documentation**
+- [Full API Reference](http://apexifyjs.jedi-studio.com)
+- [Examples Gallery](#examples)
+- [TypeScript Types](#typescript-support)
+- [Performance Guide](#performance)
+
+---
+
 ## 🤝 Contributing
 
 We welcome contributions! Here's how you can help: