Ts Gif

https://github.com/stacksjs/ts-gif
Admin
Ts Gif is a TypeScript library that provides a performant GIF encoder & decoder, supporting both...
Tokens:46,160
Snippets:472
Trust Score:10
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run Reverse Proxy via CLI

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/usage.md

Use the command-line interface to start a reverse proxy. Examples show basic usage with source and destination, custom SSL paths, and help/version commands.

```bash
rpx --from localhost:3000 --to my-project.localhost
```

```bash
rpx --from localhost:8080 --to my-project.test --keyPath ./key.pem --certPath ./cert.pem
```

```bash
rpx --help
```

```bash
rpx --version
```

--------------------------------

### Run Example Server

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/index.md

Executes the example server script to generate various test GIFs. This is useful for testing the library's capabilities.

```bash
bun examples/server.ts
```

--------------------------------

### Install rpx with bun

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx as a development dependency using bun. You can also install it globally.

```sh
bun install --dev @stacksjs/rpx
# bun add --dev @stacksjs/rpx
# bun i -d @stacksjs/rpx

# or, install globally via
bun add --global @stacksjs/rpx
```

--------------------------------

### Install rpx with brew

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx using Homebrew. This option is coming soon.

```sh
brew install rpx # coming soon
```

--------------------------------

### Install rpx with pkgx

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx using pkgx. This option is coming soon.

```sh
pkgx rpx # coming soon
```

--------------------------------

### Install ts-gif

Source: https://github.com/stacksjs/ts-gif/blob/main/README.md

Install the ts-gif library using npm or bun.

```bash
npm install ts-gif
# bun i ts-gif
```

--------------------------------

### Starting the Reverse Proxy

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/config.md

This command starts the reverse proxy service after a configuration file has been set up. Ensure your configuration file is correctly placed and formatted before execution.

```bash
./rpx start

```

--------------------------------

### Install rpx with pnpm

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx as a development dependency using pnpm. You can also install it globally.

```sh
pnpm add --save-dev @stacksjs/rpx
# pnpm i -d @stacksjs/rpx

# or, install globally via
pnpm add --global @stacksjs/rpx
```

--------------------------------

### Reverse Proxy Configuration Example

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/config.md

This snippet shows a complete example of a `reverse-proxy.config.ts` file. It demonstrates how to import types, set proxy options for 'from' and 'to' URLs, and configure detailed HTTPS settings including domain, certificate paths, and subject alternative names. Use this for advanced HTTPS configurations.

```typescript
// reverse-proxy.config.{ts,js}
import type { ReverseProxyOptions } from '@stacksjs/rpx'
import os from 'node:os'
import path from 'node:path'

const config: ReverseProxyOptions = {
  /**

   _ The from URL to proxy from.
   _ Default: localhost:5173

   */
  from: 'localhost:5173',

  /**

   _ The to URL to proxy to.
   _ Default: stacks.localhost

   */
  to: 'stacks.localhost',

  /**

   _ The HTTPS settings.
   _ Default: true
   _ If set to false, the proxy will use HTTP.
   _ If set to true, the proxy will use HTTPS.
   _ If set to an object, the proxy will use HTTPS with the provided settings.

   */
  https: {
    domain: 'stacks.localhost',
    hostCertCN: 'stacks.localhost',
    caCertPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.ca.crt`),
    certPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt`),
    keyPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt.key`),
    altNameIPs: ['127.0.0.1'],
    altNameURIs: ['localhost'],
    organizationName: 'stacksjs.org',
    countryName: 'US',
    stateName: 'California',
    localityName: 'Playa Vista',
    commonName: 'stacks.localhost',
    validityDays: 180,
    verbose: false,
  },

  /**

   _ The verbose setting.
   _ Default: false
   _ If set to true, the proxy will log more information.

   */
  verbose: false,
}

export default config

```

--------------------------------

### Writer Constructor Examples

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/configuration.md

Demonstrates initializing the Writer with minimal options, a global palette, and full animation settings.

```typescript
import { Writer } from 'ts-gif'
import { Buffer } from 'node:buffer'

// Minimal: no palette, no loop
const buf = Buffer.alloc(1024 * 1024)
const writer = new Writer(buf, 100, 100)

// With global palette
const writer = new Writer(buf, 100, 100, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000, 0x00FF00]
})

// Full animation options
const writer = new Writer(buf, 100, 100, {
  palette: generatePalette256(),
  loop: 0,        // Loop forever
  background: 1   // Clear to color 1
})
```

--------------------------------

### Install rpx with yarn

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx as a development dependency using yarn. You can also install it globally.

```sh
yarn add --dev @stacksjs/rpx
# yarn i -d @stacksjs/rpx

# or, install globally via
yarn global add @stacksjs/rpx
```

--------------------------------

### Install rpx with npm

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Install rpx as a development dependency using npm. You can also install it globally.

```sh
npm install --save-dev @stacksjs/rpx
# npm i -d @stacksjs/rpx

# or, install globally via
npm i -g @stacksjs/rpx
```

--------------------------------

### Setting Up the Writer with Options

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Demonstrates different ways to initialize the Writer class, from minimal setup to using global palettes and full options.

```typescript
// Minimal setup (requires local palettes per frame)
const writer = new Writer(buffer, width, height)

// With global palette
const writer = new Writer(buffer, width, height, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000, 0x00FF00]
})

// Full options
const writer = new Writer(buffer, width, height, {
  palette: generatePalette(256),
  loop: 0,
  background: 0
})
```

--------------------------------

### Initialize a new package using GitHub template

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/intro.md

Use this command to clone the starter kit as a template for your new package. Navigate into the new directory and install dependencies.

```bash
bunx degit stacksjs/ts-starter my-pkg
cd my-pkg

bun i # install all deps
bun run build # builds the library for production-ready use

bun run release # automates git commits, versioning, and changelog generations
```

--------------------------------

### Quantization Examples for GIF Creation

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Demonstrates examples of color quantization when creating GIFs. Quantization reduces the number of colors to optimize file size.

```typescript
import { Writer } from "@stacksjs/gif";

async function createQuantizedGif(filePath: string, frames: any[]): Promise<void> {
  // Assuming a quantization function is available or configured
  const writer = new Writer(filePath, { quantization: 'median-cut' });
  await writer.write(frames);

  console.log(`Quantized GIF written to ${filePath}`);
}
```

--------------------------------

### Install ts-gif using Package Managers

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/getting-started.md

Install the ts-gif library using your preferred package manager. Bun is recommended for its speed.

```bash
# Using bun (recommended)
bun add ts-gif

# Using npm
npm install ts-gif

# Using pnpm
pnpm add ts-gif

# Using yarn
yarn add ts-gif
```

--------------------------------

### Start a Single Reverse Proxy (Library)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/usage.md

Use this snippet to start a single reverse proxy instance using the library. Configure proxy settings like source and destination domains, URL cleaning, and HTTPS.

```typescript
import type { TlsConfig } from '@stacksjs/rpx'
import { startProxy } from '@stacksjs/rpx'

export interface CleanupConfig {
  hosts: boolean // clean up /etc/hosts, defaults to false
  certs: boolean // clean up certificates, defaults to false
}

export interface ReverseProxyConfig {
  from: string // domain to proxy from, defaults to localhost:3000
  to: string // domain to proxy to, defaults to stacks.localhost
  cleanUrls?: boolean // removes the .html extension from URLs, defaults to false
  https: boolean | TlsConfig // automatically uses https, defaults to true, also redirects http to https
  cleanup?: boolean | CleanupConfig // automatically cleans up /etc/hosts, defaults to false
  verbose: boolean // log verbose output, defaults to false
}

const config: ReverseProxyOptions = {
  from: 'localhost:3000',
  to: 'my-docs.localhost',
  cleanUrls: true,
  https: true,
  cleanup: false,
}

startProxy(config)
```

--------------------------------

### addFrame Examples

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/configuration.md

Shows how to add frames with default settings, custom delay, transparency, disposal method, and a local palette.

```typescript
// Static frame (no animation metadata)
writer.addFrame(0, 0, 100, 100, pixels)

// Animated frame with 100ms delay
writer.addFrame(0, 0, 100, 100, pixels, {
  delay: 100
})

// Frame with transparency
writer.addFrame(0, 0, 100, 100, pixels, {
  delay: 50,
  transparent: 0,    // Index 0 is transparent
  disposal: 2        // Clear after display
})

// Frame with local palette (different colors than global)
writer.addFrame(0, 0, 100, 100, pixels, {
  palette: [0xFF0000, 0x00FF00, 0x0000FF],
  delay: 100
})
```

--------------------------------

### Manual LZW Decompression Example

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Provides an example of manually decompressing GIF frame image data using readerLZWOutputIndexStream. This is an advanced use case, and most users should prefer the built-in decoding methods.

```typescript
import { readerLZWOutputIndexStream, Reader } from 'ts-gif'

const reader = new Reader(buffer)
const frame = reader.frameInfo(0)

const indices = new Uint8Array(frame.width * frame.height)
const result = readerLZWOutputIndexStream(
  buffer,
  frame.data_offset,
  indices,
  frame.width * frame.height
)

if (result === undefined) {
  console.log('Warning: LZW stream overflowed')
} else {
  // indices now contains palette indices for all pixels
}
```

--------------------------------

### Complete Animated GIF Example

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Demonstrates creating a simple animated GIF with multiple frames, custom palette, and loop settings, then saving it to a file.

```typescript
import { Writer } from 'ts-gif'
import fs from 'node:fs'

// Allocate buffer
const buf = Buffer.alloc(512 * 1024)

// Create simple animated GIF
const palette = [
  0x000000,  // Black
  0xFF0000,  // Red
  0x00FF00,  // Green
  0x0000FF   // Blue
]

const writer = new Writer(buf, 50, 50, {
  palette,
  loop: 0  // Loop forever
})

// Add frames with different colors
for (let color = 1; color <= 3; color++) {
  const pixels = new Uint8Array(50 * 50)
  pixels.fill(color)

  writer.addFrame(0, 0, 50, 50, pixels, {
    delay: 100,
    disposal: 2
  })
}

// Finalize and save
const size = writer.end()
const gifData = buf.subarray(0, size)
fs.writeFileSync('animation.gif', gifData)
```

--------------------------------

### Adding Frames with Options

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Provides examples of adding frames with various options such as delay, transparency, and local palettes.

```typescript
// Basic frame
writer.addFrame(0, 0, 100, 100, pixels)

// Frame with delay
writer.addFrame(0, 0, 100, 100, pixels, {
  delay: 50 // 500ms
})

// Frame with transparency
writer.addFrame(0, 0, 100, 100, pixels, {
  delay: 50,
  transparent: 0, // Index 0 is transparent
  disposal: 2     // Clear to background
})

// Frame with local palette
writer.addFrame(0, 0, 100, 100, pixels, {
  palette: customPalette, // Different colors for this frame
  delay: 50
})
```

--------------------------------

### Configure Multiple Reverse Proxies (Library)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/usage.md

Configure multiple reverse proxy instances using a configuration file. This example shows how to specify custom TLS certificates, cleanup options, and multiple proxy routes.

```typescript
// reverse-proxy.config.{ts,js}
import type { ReverseProxyOptions } from '@stacksjs/rpx'
import os from 'node:os'
import path from 'node:path'

const config: ReverseProxyOptions = {
  https: {
    caCertPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.ca.crt`),
    certPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt`),
    keyPath: path.join(os.homedir(), '.stacks', 'ssl', `stacks.localhost.crt.key`),
  },

  cleanup: {
    hosts: true,
    certs: false,
  },

  proxies: [
    {
      from: 'localhost:5173',
      to: 'my-app.localhost',
      cleanUrls: true,
    },
    {
      from: 'localhost:5174',
      to: 'my-api.local',
    },
  ],

  verbose: true,
}

export default config
```

--------------------------------

### Default Import Usage

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Example of how to import and use the default export to instantiate Reader and Writer.

```typescript
import gif from 'ts-gif'

const reader = new gif.Reader(buffer)
const writer = new gif.Writer(buffer, 100, 100)
```

--------------------------------

### Create GIF Animation

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Example of creating a GIF animation by initializing a Writer with palette and loop settings, then adding multiple frames with specified delays.

```typescript
const writer = new Writer(buf, 100, 100, { palette, loop: 0 })
for (const framePixels of allFrames) {
  writer.addFrame(0, 0, 100, 100, framePixels, { delay: 50 })
}
writer.end()
```

--------------------------------

### Manually Encode Frame LZW Data Example

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Example demonstrating how to manually compress and write LZW data for a frame using `writerOutputLZWCodeStream` after writing the Image Descriptor.

```typescript
import { writerOutputLZWCodeStream, Writer } from 'ts-gif'

// After writing Image Descriptor, manually compress and write LZW
let position = 100  // Hypothetical position after descriptor

const indices = new Uint8Array([0, 1, 2, 1, 0])
position = writerOutputLZWCodeStream(buf, position, 2, indices)

// buf now contains valid LZW data from byte 100 to position-1
```

--------------------------------

### Write a GIF with Frames

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Demonstrates creating a GIF by initializing a Writer with a buffer and options, adding frames with pixel data and delay, and finalizing the GIF to get the output buffer.

```typescript
const buf = Buffer.alloc(1024 * 1024)
const writer = new Writer(buf, 100, 100, {
  palette: [0xFF0000, 0x00FF00],
  loop: 0
})

writer.addFrame(0, 0, 100, 100, pixels, { delay: 100 })
const size = writer.end()
const gifData = buf.subarray(0, size)
```

--------------------------------

### Importing Types

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Example of importing type definitions for WriterOptions, FrameOptions, and Frame for use in TypeScript projects.

```typescript
import { Reader, Writer } from 'ts-gif'
import type { Frame, WriterOptions, FrameOptions } from 'ts-gif'

const options: WriterOptions = { palette: [...], loop: 0 }
const frameOptions: FrameOptions = { delay: 100 }
const frame: Frame = reader.frameInfo(0)
```

--------------------------------

### Read GIF Information and Decode Frame

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Example demonstrating how to initialize a Reader, log GIF dimensions and frame count, decode a specific frame to RGBA pixels, and retrieve frame metadata.

```typescript
const reader = new Reader(buffer)

// Get info
console.log(`${reader.width}x${reader.height}, ${reader.numFrames()} frames`)

// Decode frame
const pixels = new Uint8Array(reader.width * reader.height * 4)
reader.decodeAndBlitFrameRGBA(0, pixels)

// Get metadata
const frame = reader.frameInfo(0)
```

--------------------------------

### Import ts-gif Reader and Writer

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Import the necessary classes and types from the ts-gif library to start working with GIF files.

```typescript
import { Reader, Writer } from 'ts-gif'
import type { Frame, WriterOptions, FrameOptions } from 'ts-gif'
```

--------------------------------

### Buffer Management in GIF Operations

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Shows examples of custom buffer management for GIF reading and writing. This is useful for optimizing memory usage or integrating with custom buffer systems.

```typescript
import { Reader, Writer } from "@stacksjs/gif";

async function manageGifBuffers(filePath: string, frames: any[]): Promise<void> {
  // Example: Using a custom buffer factory
  const writer = new Writer(filePath, { bufferFactory: (size) => new Uint8Array(size) });
  await writer.write(frames);

  console.log(`GIF written with custom buffer management to ${filePath}`);
}
```

--------------------------------

### Load and Process GIF Frames with ts-gif Reader

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

This example demonstrates how to load a GIF from a file buffer, parse its metadata, and iterate through each frame to extract detailed information. It also shows how to decode frame pixels into RGBA format. Ensure you have a GIF file named 'animation.gif' in the same directory.

```typescript
import { Reader } from 'ts-gif'
import fs from 'node:fs'

// Load and parse GIF
const buffer = fs.readFileSync('animation.gif')
const reader = new Reader(buffer)

console.log(`GIF: ${reader.width}x${reader.height}, ${reader.numFrames()} frames`)
console.log(`Loop count: ${reader.getLoopCount()}`)

// Process each frame
for (let i = 0; i < reader.numFrames(); i++) {
  const frame = reader.frameInfo(i)
  console.log(`
Frame ${i}:`)
  console.log(`  Position: (${frame.x}, ${frame.y})`)
  console.log(`  Size: ${frame.width}x${frame.height}`)
  console.log(`  Delay: ${frame.delay * 10}ms`)
  console.log(`  Disposal: ${frame.disposal}`)
  console.log(`  Has local palette: ${frame.has_local_palette}`)

  // Decode to RGBA
  const pixels = new Uint8Array(reader.width * reader.height * 4)
  reader.decodeAndBlitFrameRGBA(i, pixels)
}
```

--------------------------------

### Initialize GIF Reader

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Create a new Reader instance with a Buffer containing GIF data. Access properties like width, height, and methods to get frame count and metadata.

```typescript
const reader = new Reader(buffer)

// Properties
reader.width: number              // Canvas width
reader.height: number             // Canvas height

// Methods
reader.numFrames(): number        // Total frames
reader.getLoopCount(): number | null  // Animation loops
reader.frameInfo(i): Frame        // Get frame metadata
reader.decodeAndBlitFrameRGBA(i, pixels)  // Decode to RGBA
reader.decodeAndBlitFrameBGRA(i, pixels)  // Decode to BGRA
```

--------------------------------

### Define Custom 8-Color Palette

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/configuration.md

An example of a custom 8-color palette defined as an array of 32-bit integers, representing common colors.

```typescript
const palette8 = [
  0x000000,  // Black
  0xFFFFFF,  // White
  0xFF0000,  // Red
  0x00FF00,  // Green
  0x0000FF,  // Blue
  0xFFFF00,  // Yellow
  0xFF00FF,  // Magenta
  0x00FFFF   // Cyan
]
```

--------------------------------

### Error Handling Patterns in GIF Operations

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Provides examples of how to catch and handle errors that may occur during GIF reading or writing operations. This ensures robust application behavior.

```typescript
import { Reader, Writer, GifError } from "@stacksjs/gif";

async function safeReadGif(filePath: string): Promise<void> {
  try {
    const reader = new Reader(filePath);
    await reader.read();
    console.log('GIF read successfully.');
  } catch (error) {
    if (error instanceof GifError) {
      console.error(`GIF Error: ${error.message}`);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}
```

--------------------------------

### Define a Color Palette

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Example of defining a color palette using an array of RGB values in 0xRRGGBB format. Palettes must have a power of 2 size and can be global or per-frame.

```typescript
const palette = [
  0xFF0000,  // Red
  0x00FF00,  // Green
  0x0000FF   // Blue
]
```

--------------------------------

### Add Frame to GIF

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Add a single frame to the GIF writer. This example sets a red background for a 100x100 frame, specifies a delay, and configures the frame to be cleared after display.

```typescript
import { Writer } from 'ts-gif'

const buf = Buffer.alloc(1024 * 1024)
const writer = new Writer(buf, 100, 100, {
  palette: [0xFF0000, 0x00FF00, 0x0000FF]  // Red, green, blue
})

// Single frame with red background
const pixels = new Uint8Array(100 * 100)
pixels.fill(0)  // All red

writer.addFrame(0, 0, 100, 100, pixels, {
  delay: 100,     // 1 second (100 * 10ms)
  disposal: 2,    // Clear frame
  transparent: null
})
```

--------------------------------

### Download rpx binary for Linux (x64)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Download the rpx binary for Linux (x64), make it executable, and move it to your PATH.

```sh
# Download the binary
curl -L https://github.com/stacksjs/rpx/releases/download/v0.9.1/rpx-linux-x64 -o rpx

# Make it executable
chmod +x rpx

# Move it to your PATH
mv rpx /usr/local/bin/rpx
```

--------------------------------

### Download rpx binary for Linux (arm64)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Download the rpx binary for Linux (arm64), make it executable, and move it to your PATH.

```sh
# Download the binary
curl -L https://github.com/stacksjs/rpx/releases/download/v0.9.1/rpx-linux-arm64 -o rpx

# Make it executable
chmod +x rpx

# Move it to your PATH
mv rpx /usr/local/bin/rpx
```

--------------------------------

### Get Frame Metadata

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

Iterate through all frames to get metadata such as dimensions, position, delay, and disposal method without decoding pixel data. Ensure the frame number is within the valid range.

```typescript
for (let i = 0; i < reader.numFrames(); i++) {
  const frame = reader.frameInfo(i)
  console.log(`Frame ${i}: ${frame.width}x${frame.height} at (${frame.x}, ${frame.y})`)
  console.log(`  Delay: ${frame.delay * 10}ms`)
  console.log(`  Disposal: ${frame.disposal}`)
}
```

--------------------------------

### Download rpx binary for Windows (x64)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Download the rpx binary for Windows (x64) and move it to your system's PATH.

```sh
# Download the binary
curl -L https://github.com/stacksjs/rpx/releases/download/v0.9.1/rpx-windows-x64.exe -o rpx.exe

# Move it to your PATH (adjust the path as needed)
move rpx.exe C:\\Windows\\System32\\rpx.exe
```

--------------------------------

### Writer.getOutputBufferPosition

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Gets the current position (number of bytes written) within the output buffer.

```APIDOC
## Writer.getOutputBufferPosition

### Description
Gets the current position (number of bytes written) within the output buffer.

### Signature
```typescript
getOutputBufferPosition(): number
```

### Returns
*   (number) - The current position in the buffer.
```

--------------------------------

### Download rpx binary for macOS (x64)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Download the rpx binary for macOS (x64), make it executable, and move it to your PATH.

```sh
# Download the binary
curl -L https://github.com/stacksjs/rpx/releases/download/v0.9.1/rpx-darwin-x64 -o rpx

# Make it executable
chmod +x rpx

# Move it to your PATH
mv rpx /usr/local/bin/rpx
```

--------------------------------

### Download rpx binary for macOS (arm64)

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/install.md

Download the rpx binary for macOS (arm64), make it executable, and move it to your PATH.

```sh
# Download the binary
curl -L https://github.com/stacksjs/rpx/releases/download/v0.9.1/rpx-darwin-arm64 -o rpx

# Make it executable
chmod +x rpx

# Move it to your PATH
mv rpx /usr/local/bin/rpx
```

--------------------------------

### Get GIF Frame Count

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

Retrieve the total number of frames in the GIF. Returns 0 for an empty or malformed GIF.

```typescript
const frameCount = reader.numFrames()
console.log(`Animation has ${frameCount} frames`)
```

--------------------------------

### Writer Initialization with Loop and Background

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/types.md

Initialize a Writer instance with a global palette, setting the animation to loop forever and specifying a background color.

```typescript
const writer = new Writer(buf, 100, 100, {
  palette: [0xFFFFFF, 0x000000, 0xFF0000],
  loop: 0,        // Loop forever
  background: 2   // Clear to red (index 2)
})
```

--------------------------------

### Get Output Buffer

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Retrieves the current output buffer. Use this to access raw GIF data or switch buffers.

```typescript
getOutputBuffer(): Buffer
```

```typescript
const writer = new Writer(buf, 100, 100)
writer.addFrame(0, 0, 100, 100, pixels)
const outputBuf = writer.getOutputBuffer()
```

--------------------------------

### Iterate and Get Frame Metadata

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/decoding.md

Iterates through all frames of a GIF and retrieves metadata for each frame, including position, size, delay, and disposal method.

```typescript
import { Reader } from 'ts-gif'

const reader = new Reader(buffer)

for (let i = 0; i < reader.numFrames(); i++) {
  const frame = reader.frameInfo(i)

  console.log(`Frame ${i}:`)
  console.log(`  Position: (${frame.x}, ${frame.y})`)
  console.log(`  Size: ${frame.width}x${frame.height}`)
  console.log(`  Delay: ${frame.delay * 10}ms`)
  console.log(`  Disposal: ${frame.disposal}`)
  console.log(`  Transparent index: ${frame.transparent*index}`)
  console.log(`  Interlaced: ${frame.interlaced}`)
  console.log(`  Has local palette: ${frame.has*local*palette}`)
}
```

--------------------------------

### Main Entry Point Exports

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/architecture.md

The index.ts file serves as the main entry point, exporting the Reader and Writer classes along with low-level compression functions. It also provides a default export containing Reader and Writer for convenient access.

```typescript
export { Reader, readerLZWOutputIndexStream, Writer, writerOutputLZWCodeStream }
export default gif  // Default export contains Reader and Writer
```

--------------------------------

### Initialize GIF Writer

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/quick-reference.md

Instantiate a Writer with a Buffer, dimensions, and options. Use methods to add frames, finalize the GIF, and manage the output buffer.

```typescript
const writer = new Writer(buffer, width, height, options)

// Methods
writer.addFrame(x, y, w, h, pixels, options): number
writer.end(): number
writer.getOutputBuffer(): Buffer
writer.setOutputBuffer(buf): void
writer.getOutputBufferPosition(): number
writer.setOutputBufferPosition(pos): void
```

--------------------------------

### Get Output Buffer Position

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Returns the current write position in bytes within the output buffer, indicating the current size of the GIF file being written.

```typescript
getOutputBufferPosition(): number
```

```typescript
const writer = new Writer(buf, 100, 100)
console.log(`Initial position: ${writer.getOutputBufferPosition()}`)

writer.addFrame(0, 0, 100, 100, pixels)
console.log(`After frame: ${writer.getOutputBufferPosition()}`)

const size = writer.end()
console.log(`Final size: ${size}`)
```

--------------------------------

### Run Tests

Source: https://github.com/stacksjs/ts-gif/blob/main/README.md

Execute the test suite for the ts-gif library using bun.

```bash
bun test
```

--------------------------------

### Writer Constructor with Options

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/configuration.md

Instantiate the Writer class with optional configuration for GIF-wide settings like loop count, global palette, and background color.

```typescript
const writer = new Writer(buffer, width, height, options?: WriterOptions)
```

--------------------------------

### Get Frame Information

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/examples.md

Iterates through all frames of a GIF and logs detailed information for each, including position, size, delay, transparency index, disposal method, and interlacing status.

```typescript
const reader = new Reader(buffer)

for (let i = 0; i < reader.numFrames(); i++) {
  const frame = reader.frameInfo(i)
  
  console.log(`Frame ${i}:`)
  console.log(`  Position: (${frame.x}, ${frame.y})`)
  console.log(`  Size: ${frame.width}x${frame.height}`)
  console.log(`  Delay: ${frame.delay * 10}ms`)
  console.log(`  Transparent color: ${frame.transparent_index}`)
  console.log(`  Disposal: ${frame.disposal}`)
  console.log(`  Interlaced: ${frame.interlaced}`)
}
```

--------------------------------

### Importing ts-gif Exports

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Demonstrates how to import specific components like Reader and Writer, or the entire library using the default export.

```typescript
import { Reader, Writer, readerLZWOutputIndexStream, writerOutputLZWCodeStream } from 'ts-gif'

// Or use default export:
import gif from 'ts-gif'
const { Reader, Writer } = gif
```

--------------------------------

### Instantiate Writer with Global Palette

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Create a new Writer instance for a 100x100 GIF with a predefined global color palette and set to loop indefinitely.

```typescript
import { Writer } from 'ts-gif'

// Allocate 1MB buffer
const buf = Buffer.alloc(1024 * 1024)

// Create 100x100 writer with global palette
const writer = new Writer(buf, 100, 100, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000],
  loop: 0  // Loop forever
})
```

--------------------------------

### Writer Class Constructor

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Initializes a new Writer instance to create GIF data. It requires a buffer to write to, the dimensions of the GIF, and optional configuration.

```APIDOC
## Writer Constructor

### Description
Initializes a new Writer instance to create GIF data. It requires a buffer to write to, the dimensions of the GIF, and optional configuration.

### Signature
```typescript
constructor(buffer: Buffer, width: number, height: number, options?: WriterOptions)
```

### Parameters

*   **buffer** (Buffer) - The buffer to write GIF data into.
*   **width** (number) - The width of the GIF in pixels.
*   **height** (number) - The height of the GIF in pixels.
*   **options** (WriterOptions) - Optional configuration for the writer.
```

--------------------------------

### Catch Invalid GIF Header Error

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/errors.md

Handle errors when the input buffer does not start with the correct GIF signature. This typically occurs when the file is not a valid GIF or the data is truncated.

```typescript
try {
  const reader = new Reader(buffer)
} catch (error) {
  if (error.message === 'Invalid GIF 87a/89a header.') {
    console.log('File is not a valid GIF')
  }
}
```

--------------------------------

### Minimal Writer Initialization

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/types.md

Initialize a new Writer instance with minimal configuration, relying on local palettes per frame.

```typescript
const writer = new Writer(buf, 100, 100)
```

--------------------------------

### Retrieve GIF Output Buffer

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Obtains the raw buffer containing the generated GIF data. You can also get the current position (bytes written) or a subarray of only the written portion.

```typescript
// Get the output buffer
const outputBuffer = writer.getOutputBuffer()

// Get current position (bytes written)
const position = writer.getOutputBufferPosition()

// Get only the written portion
const gifData = outputBuffer.subarray(0, position)
```

--------------------------------

### getOutputBufferPosition()

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Gets the current write position within the output buffer, indicating the number of bytes written so far. This value represents the current size of the GIF file being constructed.

```APIDOC
## getOutputBufferPosition()

### Description
Returns the current write position (number of bytes written) in the output buffer.

### Method
GET

### Endpoint
N/A (Class Method)

### Returns
- **number**: Byte position, which is also the current GIF file size.
```

--------------------------------

### Writer Constructor

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Initializes a new Writer instance to encode GIF data. It requires an output buffer, dimensions, and optional configuration for palettes and looping.

```APIDOC
## Writer Constructor

### Writer(buf, width, height, options)

Initializes a new Writer instance.

#### Parameters

- **buf** (Buffer) - Required - Output buffer for GIF data. Must be large enough to hold the complete GIF. Recommended size: `1024 * 1024` for typical images.
- **width** (number) - Required - Canvas width in pixels. Must be > 0 and ≤ 65535.
- **height** (number) - Required - Canvas height in pixels. Must be > 0 and ≤ 65535.
- **options** (WriterOptions) - Optional - Configuration object. See [WriterOptions](../types.md#writeroptions).

#### Throws

- Error: "Width/Height invalid." - `width` or `height` is ≤ 0 or > 65535.

#### Example

```typescript
import { Writer } from 'ts-gif'

// Allocate 1MB buffer
const buf = Buffer.alloc(1024 * 1024)

// Create 100x100 writer with global palette
const writer = new Writer(buf, 100, 100, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000],
  loop: 0  // Loop forever
})
```
```

--------------------------------

### Get GIF Loop Count Information

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/decoding.md

Retrieves and interprets the loop count from the GIF's animation extension to determine if it plays once, loops indefinitely, or loops a specific number of times.

```typescript
const loopCount = reader.getLoopCount()

if (loopCount === null) {
  console.log('No animation extension (single play)')
} else if (loopCount === 0) {
  console.log('Loops forever')
} else {
  console.log(`Loops ${loopCount} times`)
}
```

--------------------------------

### Create Static GIF

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/examples.md

Creates a static GIF with a specified palette (Red, Green, Blue) and a red background. The output GIF is then saved to a file.

```typescript
import { Writer } from 'ts-gif'
import fs from 'node:fs'

const buffer = Buffer.alloc(1024 * 1024)

const writer = new Writer(buffer, 100, 100, {
  palette: [0xFF0000, 0x00FF00, 0x0000FF]  // Red, Green, Blue
})

// Create red background
const pixels = new Uint8Array(100 * 100)
pixels.fill(0)  // Index 0 = red

writer.addFrame(0, 0, 100, 100, pixels)
const size = writer.end()

fs.writeFileSync('static.gif', buffer.subarray(0, size))
```

--------------------------------

### Creating an Animated GIF

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Illustrates the process of creating an animated GIF by providing multiple frames to the Writer. Each frame can have its own configuration.

```typescript
import { Writer } from "@stacksjs/gif";

async function createAnimation(filePath: string, frameData: any[]): Promise<void> {
  const writer = new Writer(filePath);
  await writer.write(frameData);

  console.log(`Animation written to ${filePath}`);
}
```

--------------------------------

### Importing Low-Level Functions

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Demonstrates importing and using both high-level classes and low-level stream manipulation functions.

```typescript
import { Reader, Writer, readerLZWOutputIndexStream, writerOutputLZWCodeStream } from 'ts-gif'

// Decompress frame manually
const indices = new Uint8Array(100 * 100)
readerLZWOutputIndexStream(buffer, offset, indices, 10000)

// Compress frame manually
const newPos = writerOutputLZWCodeStream(buffer, pos, 2, indices)
```

--------------------------------

### Get GIF Loop Count

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

Retrieve the animation loop count from the Netscape 2.0 extension. Returns null if no animation loop extension is present, 0 for infinite loops, or a number > 0 for a specific number of repetitions.

```typescript
const loopCount = reader.getLoopCount()

if (loopCount === null) {
  console.log('GIF plays once')
} else if (loopCount === 0) {
  console.log('GIF loops forever')
} else {
  console.log(`GIF loops ${loopCount} times`)
}
```

--------------------------------

### Reader Constructor

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

Initializes a new Reader instance by parsing GIF file data. It validates the GIF header and extracts essential metadata.

```APIDOC
## Reader(buf)

### Description
Initializes a new Reader instance by parsing GIF file data. It validates the GIF header and extracts essential metadata.

### Parameters
#### Path Parameters
- **buf** (Buffer) - Required - GIF file data as a Node.js Buffer. Must contain a valid GIF87a or GIF89a file.

### Throws
- Error: "Invalid GIF 87a/89a header." - Buffer does not start with valid GIF signature bytes (0x47 0x49 0x46 0x38).
- Error: "Invalid block size" - GIF file contains malformed data block with invalid size.
- Error: "Invalid graphics extension block." - Graphics control extension has invalid format or size.
- Error: "Unknown graphic control label: 0x..." - GIF contains unrecognized graphics control extension.
- Error: "Unknown gif block: 0x..." - GIF contains unrecognized block type.

### Example
```typescript
import { Reader } from 'ts-gif'
import fs from 'node:fs'

const buffer = fs.readFileSync('animation.gif')
const reader = new Reader(buffer)

console.log(`GIF size: ${reader.width}x${reader.height}`)
console.log(`Frames: ${reader.numFrames()}`)
```
```

--------------------------------

### Writing a GIF File

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Shows how to write a GIF file using the Writer class. This involves providing frame data and configuration.

```typescript
import { Writer } from "@stacksjs/gif";

async function writeGif(filePath: string, frames: any[]): Promise<void> {
  const writer = new Writer(filePath);
  await writer.write(frames);

  console.log(`GIF written to ${filePath}`);
}
```

--------------------------------

### Named Imports (Recommended)

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/exports.md

Recommended import pattern for using Reader and Writer classes directly.

```typescript
import { Reader, Writer } from 'ts-gif'

const reader = new Reader(buffer)
const writer = new Writer(buffer, 100, 100)
```

--------------------------------

### Writer Initialization with Global Palette

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/types.md

Initialize a Writer instance providing a global color palette. This palette will be used by default for all frames unless overridden.

```typescript
const writer = new Writer(buf, 100, 100, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000]
})
```

--------------------------------

### Initialize Reader with Buffer

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/reader.md

Create a new Reader instance by passing a Node.js Buffer containing GIF file data. Ensure the buffer contains a valid GIF87a or GIF89a file.

```typescript
import { Reader } from 'ts-gif'
import fs from 'node:fs'

const buffer = fs.readFileSync('animation.gif')
const reader = new Reader(buffer)

console.log(`GIF size: ${reader.width}x${reader.height}`)
console.log(`Frames: ${reader.numFrames()}`)
```

--------------------------------

### Reading a GIF File

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Demonstrates how to read a GIF file using the Reader class. Ensure the file path is correct.

```typescript
import { Reader } from "@stacksjs/gif";

async function readGif(filePath: string): Promise<void> {
  const reader = new Reader(filePath);
  const gif = await reader.read();

  console.log(gif);
}
```

--------------------------------

### Palette Management in GIF Creation

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Demonstrates how to manage palettes when creating GIFs. This can involve global or local palettes per frame.

```typescript
import { Writer } from "@stacksjs/gif";

async function createGifWithPalette(filePath: string, frames: any[], palette: any): Promise<void> {
  const writer = new Writer(filePath, { palette });
  await writer.write(frames);

  console.log(`GIF with custom palette written to ${filePath}`);
}
```

--------------------------------

### end Method

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Finalizes the GIF file by writing the trailer and returning the total size of the generated GIF data.

```APIDOC
## end Method

### end()

Finalizes the GIF by writing the trailer byte (0x3B) and closing the file structure. Must be called after all frames are added. Subsequent calls to `end()` are safe and return the same position.

#### Returns

- **number** - Final byte position in the output buffer (GIF file size).

#### Example

```typescript
const writer = new Writer(buf, 100, 100)
writer.addFrame(0, 0, 100, 100, pixels)
const size = writer.end()

// Write to file
const gifData = buf.subarray(0, size)
fs.writeFileSync('output.gif', gifData)
```
```

--------------------------------

### Simple Animation Creation

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Demonstrates creating a simple animated GIF by adding multiple frames with cycling colors and specified delays.

```typescript
import { Writer } from 'ts-gif'

const width = 50
const height = 50
const buffer = Buffer.alloc(512 * 1024)

const palette = [
  0x000000, // Black
  0xFF0000, // Red
  0x00FF00, // Green
  0x0000FF, // Blue
]

const writer = new Writer(buffer, width, height, {
  palette,
  loop: 0 // Loop forever
})

// Create frames for color cycling
const pixels = new Uint8Array(width * height)

for (let color = 1; color <= 3; color++) {
  pixels.fill(color)
  writer.addFrame(0, 0, width, height, pixels, {
    delay: 100, // 1 second per frame
    disposal: 2
  })
}

const size = writer.end()
```

--------------------------------

### WriterOptions Interface

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/types.md

Configuration options for the Writer constructor. Use this to set animation loop count, global color palette, and background color.

```typescript
interface WriterOptions {
  loop?: number
  palette?: number[]
  background?: number
}
```

--------------------------------

### Handling Transparency in GIFs

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/DOCUMENTATION_MANIFEST.txt

Illustrates how to handle transparency information when reading or writing GIFs. This includes setting transparent colors and disposal methods.

```typescript
import { Writer } from "@stacksjs/gif";

async function createGifWithTransparency(filePath: string, frames: any[]): Promise<void> {
  const writer = new Writer(filePath);
  // Configure transparency for frames
  await writer.write(frames.map(frame => ({ ...frame, transparency: true, disposal: 2 })));

  console.log(`GIF with transparency written to ${filePath}`);
}
```

--------------------------------

### Write Animated GIF with Multiple Frames

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/index.md

Creates a simple 2-frame animated GIF with red and green frames and saves it to a file. This demonstrates the basic process of initializing a writer, adding frames with pixel data and delays, and finalizing the GIF.

```typescript
import { Writer } from 'ts-gif'
import fs from 'node:fs'

const buffer = Buffer.alloc(1024 * 1024)

// Create a simple 2-frame animation
const writer = new Writer(buffer, 100, 100, {
  palette: [0xFF0000, 0x00FF00, 0x0000FF],
  loop: 0  // Loop forever
})

// Frame 1: Red
const pixels1 = new Uint8Array(100 * 100)
pixels1.fill(0)
writer.addFrame(0, 0, 100, 100, pixels1, { delay: 100 })

// Frame 2: Green
const pixels2 = new Uint8Array(100 * 100)
pixels2.fill(1)
writer.addFrame(0, 0, 100, 100, pixels2, { delay: 100 })

// Finalize
const size = writer.end()
fs.writeFileSync('output.gif', buffer.subarray(0, size))
```

--------------------------------

### Basic GIF Creation

Source: https://github.com/stacksjs/ts-gif/blob/main/docs/guide/encoding.md

Creates a simple GIF with a single frame using the Writer class. Requires allocating a buffer and defining dimensions and basic options.

```typescript
import { Writer } from 'ts-gif'
import { writeFileSync } from 'node:fs'

// Allocate buffer for output
const buffer = Buffer.alloc(1024 * 1024)

// Create writer with dimensions and options
const writer = new Writer(buffer, 100, 100, {
  palette: [0x000000, 0xFFFFFF, 0xFF0000, 0x00FF00],
  loop: 0
})

// Add a frame
const pixels = new Uint8Array(100 * 100)
pixels.fill(1) // Fill with white (palette index 1)

writer.addFrame(0, 0, 100, 100, pixels)

// Finalize and get output size
const size = writer.end()

// Write to file
writeFileSync('output.gif', buffer.subarray(0, size))
```

--------------------------------

### Reader Constructor

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/configuration.md

Instantiate the Reader class with a buffer containing GIF data. The Reader has no configurable options.

```typescript
const reader = new Reader(buffer)
```

--------------------------------

### Import Writer Class

Source: https://github.com/stacksjs/ts-gif/blob/main/_autodocs/api-reference/writer.md

Import the Writer class from the ts-gif library.

```typescript
import { Writer } from 'ts-gif'
```
Tokens:
Raw