npm package: @ferchy/n8n-nodes-aimc-toolkit
Description: AIMC Toolkit nodes for n8n: code execution and media operations.
Author: Ferchy
Latest version: 0.1.45

# AIMC Toolkit for n8n

AIMC Toolkit is a community node package for n8n with focused nodes:

- **AIMC Code**: run JavaScript with a practical toolbox of libraries.
- **AIMC Media**: FFmpeg-powered media operations without extra glue nodes.
- **AIMC Social Scraper**: scrape content from social media platforms (coming soon).

## Why I Built This

My primary goal is simple: make as much **free, open-source tooling** usable inside n8n and help people avoid stacking subscriptions that add up fast. There’s no need to reinvent the wheel, but there’s also no reason to keep paying for things that already exist in open source.

A lot of “best tool” videos online are affiliate-driven, and not everyone has the same operational budget. AIMC Toolkit is my way of giving the community a practical, honest alternative: solid building blocks that save time and money while keeping your workflows clean.

n8n is powerful, but real workflows often need basic utilities (validation, parsing, HTTP) and media tasks (convert, compress, merge). I built AIMC Toolkit to remove the busywork and keep workflows short, readable, and fast.

**Inspiration**: The original idea was sparked by Kenkaii's SuperCode. I'm grateful for that work and built AIMC Toolkit as my own version, tailored to my needs and expanded with improvements over time.

**Note**: Of course there will be some bugs - that's obvious! We're aware of them and the best thing is that we will continue to improve, so please be patient!

## Who This Is For

- Automation builders who want fewer nodes and faster iterations.
- Agencies handling content workflows, clips, and format conversions.
- Founders and teams building internal tooling on n8n.
- Power users who want a better code node and real media ops.

## Why AIMC Toolkit

- **Fewer nodes, cleaner flows**: consolidate multiple steps into one code node.
- **Media ready**: convert, compress, merge, and inspect media in one place.
- **Social scraping**: scrape social media platforms with a simple UI (coming soon).
- **Practical libraries**: parsing, validation, dates, and web utilities built in.

## Installation

### Prerequisites
- n8n is already installed and running (self-hosted or desktop).
- Community nodes are enabled in your n8n instance.
- n8n Cloud does not support community nodes.

### Community Nodes (Recommended)
1. Open **Settings > Community Nodes** in n8n.
2. Install: `@ferchy/n8n-nodes-aimc-toolkit`.

### Manual
```bash
npm install @ferchy/n8n-nodes-aimc-toolkit
```

## Nodes

### AIMC Code

**Features**
- Run JavaScript or Python.
- Run once for all items or once per item.
- Access libraries as globals (axios, _, zod) or via libs.
- Built-in helpers (utils.now, utils.safeJson, utils.toArray).
- **AIMC Connect Mode**: optional AI connectors for LLMs, tools, memory, and more.

**Example: normalize data**
```javascript
const rows = $input.all().map((i) => i.json);
const ids = rows.map(() => nanoid());

return rows.map((row, index) => ({
  ...row,
  id: ids[index],
  normalizedEmail: validator.normalizeEmail(row.email || ''),
  createdAt: utils.now(),
}));
```

**Prompt starter (for GPT/Claude)**
If you want AI to generate your node code, paste this prompt into ChatGPT, Claude, or any GPT-style tool and fill in your task:
```text
You are writing code for an n8n AIMC Code node.
Goal: <describe what you want to do>
Execution mode: <Run Once for Each Item OR Run Once for All Items>
Inputs: items are available as `items` (all) or `item` (single)
Return: return a plain object or array of objects (JSON-safe)
Libraries (globals): axios, lodash (_), zod (z), joi (Joi), yup, Ajv, validator, dayjs, dateFns, dateFnsTz, moment,
cheerio, papaparse (Papa), csvParse, yaml (YAML), ini, xml2js, XMLParser, qs, FormData, uuid, nanoid, bytes, cronParser, ms,
fuzzy, stringSimilarity, slug, pluralize, jsonDiff, htmlToText, marked, Handlebars, qrcode/QRCode, ytdl, ffmpeg, ffmpegStatic, ffprobeStatic,
pdfLib, archiver, Jimp, pLimit, math, currency.
Helpers: utils.now(), utils.safeJson(), utils.toArray()
Please return only the JavaScript code for the AIMC Code node.
```

## Python Support (AIMC Code)

Python is optional. **JavaScript works out of the box.**  
If you switch the node to Python mode, Python must be installed on the same host/container where n8n runs.

### AIMC Code vs n8n Native Python

| Feature | n8n Native Python (v2+) | AIMC Code Python |
|---------|-------------------------|------------------|
| **Setup Required** | Task Runners in External Mode | Just Python installed |
| **Configuration** | Server-level config needed | Works out of the box |
| **Pre-loaded Libraries** | Standard library only | All npm libs available as globals |
| **JavaScript Libraries** | ❌ Not available | ✅ Full access (axios, lodash, etc.) |
| **Package Management** | Manual pip install | Auto-install option in node |
| **Complexity** | More complex setup | Simpler, just needs Python binary |

**Why AIMC Code?** n8n's native Python requires configuring Task Runners, which is extra infrastructure work. AIMC Code just needs Python installed - no server config required. Plus, you get access to all the JavaScript libraries as globals, which n8n's native Python doesn't offer.

We do **not** auto-install Python during npm install because system-level installs are fragile in containers and often fail or get blocked. This keeps installs reliable and avoids broken deployments.
**Why this approach:** n8n runs inside containers, npm is JavaScript-only, and many hosts block install scripts. Letting you install Python on the host keeps it stable, predictable, and under your control.

**Options in the node**
- **Python Path**: path to the Python binary (default `python3`).
- **Python Packages**: comma-separated list to install.
- **Auto-install Python Packages**: if enabled, the node runs `pip install --user` before execution.

If you prefer manual setup, install packages on the host (or container) and keep auto-install off.

### AIMC Media

**Operations**
- Convert / Transcode
- Compress
- Extract Audio
- Merge Video + Audio
- Metadata (ffprobe)

**Key Options**
- **Input Mode**: Binary, File Path, or URL (download from web)
- **Output Mode**: Binary or File Path
- **Output Format**: mp4, webm, mov, mp3, wav, and more
- **Extra FFmpeg Args**: one per line for advanced control

**Example: download and convert from URL**
```
Operation: Convert / Transcode
Input Mode: URL
Input URL: https://example.com/video.mp4
Output Format: webm
```

## FFmpeg Setup (AIMC Media)

FFmpeg must be installed on the same host/container where n8n runs. AIMC Media uses, in order:
1. `FFMPEG_PATH` / `FFPROBE_PATH` environment variables
2. System FFmpeg on `PATH`
3. Bundled `ffmpeg-static` / `ffprobe-static` (if available)

**Install examples**
- Docker (inside container): `docker exec -it <container> apk add --no-cache ffmpeg`
- Dockerfile (any host): `FROM n8nio/n8n:latest` then `RUN apk add --no-cache ffmpeg`
- Debian/Ubuntu: `apt-get update && apt-get install -y ffmpeg`
- macOS (local dev): `brew install ffmpeg`

**Quick test**: use `http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerEscapes.mp4` as Input URL.

### AIMC Social Scraper

**Coming Soon!**

Social media scraping functionality is currently under development.

## Library Reference (AIMC Code)

Libraries are available as globals or via `libs.<name>`. Each group lists what’s included and what it’s used for.

### HTTP and Networking
- `axios` — HTTP client
- `qs` — querystring builder/parser
- `FormData` — multipart uploads
- `httpProxyAgent` — HTTP(S) proxy routing
- `socksProxyAgent` — SOCKS proxy support

### Parsing and Formats
- `YAML`, `toml`, `ini` — config formats
- `xml2js`, `XMLParser` — XML parsing
- `papaparse` / `Papa`, `csvParse` — CSV parsing
- `protobufjs` / `protobuf` — Protobuf
- `Handlebars` — templates

### Validation and Schema
- `zod` / `z`, `joi` / `Joi`, `yup` — schemas
- `Ajv` — JSON Schema validation
- `validator` — common validators

### Dates, Time, and Scheduling
- `dayjs`, `dateFns`, `dateFnsTz`, `moment` — date utilities
- `cronParser` — cron parsing
- `ms` — duration parsing

### Text, Search, and Similarity
- `cheerio` — HTML parsing
- `fuzzy` — fuzzy search
- `stringSimilarity` — similarity score
- `marked` — Markdown to HTML
- `slug`, `pluralize`, `htmlToText` — text utilities

### Utilities and Math
- `_` / `lodash` — data helpers
- `uuid`, `nanoid` — IDs
- `bytes` — byte parsing/formatting
- `jsonDiff` — JSON diffing
- `pRetry`, `pLimit` — retry & concurrency
- `math`, `currency` — math and money

### Language and NLP
- `franc` — language detection
- `compromise` — NLP helpers

### Media and Files
- `QRCode` / `qrcode` — QR generation
- `ytdl` — media downloads
- `ffmpeg`, `ffmpegStatic`, `ffprobeStatic` — FFmpeg pipelines
- `pdfLib` — PDF creation/editing
- `archiver` — zip archives
- `Jimp` — image processing

### Database
- `knex` — SQL query builder

### Other Utilities
- `phoneNumber` — phone parsing
- `iban` — IBAN validation

### Optional Native Helpers
- `bufferutil` — optional native buffer helpers (if installed)
- `utf8Validate` — optional UTF-8 validation (if installed)

## Configuration

Environment variables:
- FFMPEG_PATH: custom FFmpeg binary path
- FFPROBE_PATH: custom ffprobe binary path

## Troubleshooting

- **FFmpeg not found**: install FFmpeg or set FFMPEG_PATH.
- **Large files**: use File Path input mode.
- **Binary output missing**: check Output Mode and Output Binary Property.

## Legal Disclaimer

The AIMC Social Scraper uses web scraping techniques. This is not an official API integration.

**Important:**
- Users must comply with platform Terms of Service
- Users must comply with applicable laws (GDPR, CCPA, etc.)
- The authors are not responsible for misuse

**Use at your own risk.**

## License

MIT