bg-remover

# Background Remover Skill

Remove backgrounds from images using FAL.ai's BiRefNet v2 model. Uses Bun for fast TypeScript execution with inline scripts.

## Prerequisites

This skill requires:
- **Bun** - Fast JavaScript runtime
- **FAL_KEY** - FAL.ai API key set as environment variable

### Checking for Bun

Before running scripts, verify Bun is installed:

```bash
which bun
```

If Bun is not installed, **ask the user for permission** before installing:

```bash
npm install -g bun
```

### Setting up FAL.ai

1. Get an API key from https://fal.ai/dashboard/keys
2. Set the environment variable: `export FAL_KEY="your-key-here"`

## Basic Usage

Remove background from an image using a heredoc script:

```bash
bun run - << 'EOF'
import { fal } from "@fal-ai/client";
import { readFileSync, writeFileSync } from "fs";
import { basename, dirname, join } from "path";

const imagePath = "INPUT_IMAGE_PATH";
const imageBuffer = readFileSync(imagePath);
const fileName = basename(imagePath);
const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

// Upload to FAL storage
const file = new File([imageBuffer], fileName, { type: mimeType });
const imageUrl = await fal.storage.upload(file);
console.log("Uploaded:", imageUrl);

// Remove background
const result = await fal.subscribe("fal-ai/birefnet/v2", {
  input: {
    image_url: imageUrl,
    model: "General Use (Light)",
    operating_resolution: "1024x1024",
    output_format: "png"
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS" && update.logs) {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

// Download and save result
const outputUrl = result.data.image.url;
const response = await fetch(outputUrl);
const buffer = Buffer.from(await response.arrayBuffer());

const dir = dirname(imagePath);
const nameWithoutExt = basename(imagePath, basename(imagePath).match(/\.[^.]+$/)?.[0] || "");
const outputPath = join(dir, `${nameWithoutExt}-nobg.png`);

writeFileSync(outputPath, buffer);
console.log("Saved:", outputPath);
EOF
```

Replace `INPUT_IMAGE_PATH` with the actual path to the image.

## Model Options

The BiRefNet model supports different configurations:

### Model Variants
- `"General Use (Light)"` - Fast, good for most images (default)
- `"General Use (Heavy)"` - Higher quality, slower processing
- `"Portrait"` - Optimized for human subjects
- `"Matting"` - Best for complex edges like hair

### Operating Resolutions
- `"1024x1024"` - Standard quality (default)
- `"2048x2048"` - Higher detail for large images

### Additional Options
- `refine_foreground: true` - Improve edge quality
- `output_format: "png"` - Always use PNG for transparency

## Configuration Example

For high-quality portrait extraction:

```bash
bun run - << 'EOF'
import { fal } from "@fal-ai/client";
import { readFileSync, writeFileSync } from "fs";
import { basename, dirname, join } from "path";

const imagePath = "INPUT_IMAGE_PATH";
const imageBuffer = readFileSync(imagePath);
const fileName = basename(imagePath);
const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

const file = new File([imageBuffer], fileName, { type: mimeType });
const imageUrl = await fal.storage.upload(file);

const result = await fal.subscribe("fal-ai/birefnet/v2", {
  input: {
    image_url: imageUrl,
    model: "Portrait",
    operating_resolution: "2048x2048",
    refine_foreground: true,
    output_format: "png"
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS" && update.logs) {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

const response = await fetch(result.data.image.url);
const buffer = Buffer.from(await response.arrayBuffer());

const dir = dirname(imagePath);
const nameWithoutExt = basename(imagePath, basename(imagePath).match(/\.[^.]+$/)?.[0] || "");
const outputPath = join(dir, `${nameWithoutExt}-nobg.png`);

writeFileSync(outputPath, buffer);
console.log("Saved:", outputPath);
EOF
```

## Key Principles

1. **Check prerequisites**: Always verify Bun is installed before running
2. **Ask before installing**: Get user permission before `npm install -g bun`
3. **Use heredocs**: Run inline scripts for one-off operations
4. **Preserve location**: Save output next to input with `-nobg` suffix
5. **Always PNG**: Output format must be PNG for transparency

## Workflow

1. **Verify Bun** is installed (offer to install if not)
2. **Verify FAL_KEY** is set
3. **Run the script** with the input image path
4. **Check the output** - view the saved PNG with transparent background

## Error Recovery

If a script fails:
1. Check FAL_KEY is set: `echo $FAL_KEY`
2. Verify image path exists and is readable
3. Check FAL.ai dashboard for quota/billing issues
4. Try a smaller image if upload fails

## API Response Format

The BiRefNet model returns:

```json
{
  "image": {
    "url": "https://...",
    "width": 1024,
    "height": 1024,
    "content_type": "image/png",
    "file_name": "birefnet-output.png"
  }
}
```

## Advanced Usage

For batch processing, URL-based inputs, or integration with other tools, see `references/guide.md`.