n8n-nodes-gamdl

An n8n community node that runs a bundled gamdl executable and returns every downloaded file as an n8n binary item.

This project is an initial scaffold. The standalone gamdl executables are not included yet, so the node deliberately fails with an actionable message until they are added.

Features

• Accepts an HTTPS Apple Music URL.
• Stores the complete cookies.txt content as an encrypted n8n credential.
• Creates a unique private working directory for every input item.
• Writes cookies.txt with mode 0600.
• Selects an embedded executable for Linux x64 or Linux arm64.
• Returns one item per file with binary property data, plus fileName and POSIX-style relativePath metadata.
• Deletes cookies, downloads, and intermediate files in all success and error paths.
• Supports n8n's Continue On Fail behavior.

Installation

Once published:

npm install n8n-nodes-gamdl

Or install n8n-nodes-gamdl from Settings → Community Nodes in a compatible self-hosted n8n instance.

Credentials

Create a Gamdl Cookies credential and paste the complete Netscape-format content of your Apple Music cookies.txt file into Cookies.txt Content. The credential is marked as a password field, so n8n stores it through its credential encryption mechanism and masks it in the editor.

Treat this value like a password. Use an account intended for this workflow and rotate the cookies if they are exposed.

Usage

1. Add the Gamdl node.
2. Select the Gamdl Cookies credential.
3. Enter an https://music.apple.com/... URL.
4. Optionally adjust the timeout.
5. Connect the output to a node that accepts binary data. Each downloaded file is emitted under binary property data.

The output JSON resembles:

{
  "fileName": "01 Example.m4a",
  "relativePath": "Artist/Album/01 Example.m4a"
}

Development

Requirements: Node.js 20.12 or newer and npm.

npm install
npm run lint
npm test
npm run build
npm pack --dry-run

For local development before binaries are bundled, set GAMDL_BINARY_PATH to a gamdl-compatible executable. This override is resolved to an absolute path and must be executable.

Bundling standalone gamdl

Place release artifacts at:

bin/
├── linux-x64/
│   ├── gamdl
│   └── lib/
└── linux-arm64/
    ├── gamdl
    └── lib/

The build copies the complete bin tree into dist/bin, and the published package contains only dist. The node never downloads code at runtime.

Recommended release strategy:

1. Pin the gamdl source version and record it in release notes.
2. Build in architecture-specific Linux/musl containers matching the official n8n image, with Python, Rust, and Nuitka.
3. Begin with Nuitka standalone so missing modules and data files are visible; optionally move to onefile later.
4. Include and test the gamdl._ammuxer PyO3 extension and CA certificate data.
5. Run gamdl --help, a cookie-file permission test, and an authorized end-to-end fixture on both architectures.
6. Copy the launchers/bundles into the paths above, set executable mode, build, and inspect npm pack --dry-run.
7. Publish only when both architecture jobs pass. Generate checksums and an SBOM in CI.

If Nuitka emits a directory rather than one file, keep each complete bundle below its platform directory and name its entrypoint gamdl.

Build and test the Linux bundles with Docker

Docker Buildx can produce a real Linux/musl bundle even when development happens on macOS. The build is pinned to gamdl 3.8.5 by default and validates gamdl --version and gamdl --help inside the official n8n image before exporting the files. Building against musl is essential: a Debian/glibc bundle fails in the Alpine-based n8n image with missing symbols such as close_range and fcntl64.

On Apple Silicon, build arm64 first because it runs natively:

npm run build:gamdl:linux-arm64

Build x64 separately (Docker Desktop uses CPU emulation on an arm64 Mac):

npm run build:gamdl:linux-x64

To test another pinned gamdl release:

GAMDL_VERSION=3.8.5 npm run build:gamdl:linux-arm64

Each command exports a small gamdl launcher plus the complete Nuitka standalone directory under lib/, restores executable mode on the launcher, and launches it in n8nio/n8n:latest. Set N8N_IMAGE to test another tag. The build uses a staging directory and replaces the previous platform bundle only after validation, preventing stale glibc libraries from remaining beside a new musl build. The compiled entrypoint is named gamdl-cli: calling it gamdl would collide with the Python package directory required for gamdl/_ammuxer.so. Do not copy only the launcher: the adjacent lib/ directory is part of the executable bundle.

The build disables yt-dlp's generated lazy_extractors catalogue. That single generated module can exhaust several gigabytes of RAM while GCC compiles it, while gamdl only uses yt-dlp as a download library. yt-dlp falls back to its regular extractor modules if they are ever needed.

Limitations

• V1 supports Linux/musl x64 and arm64 for the official n8n container. Linux/glibc, macOS, and Windows are not included in the published bundle.
• Some gamdl modes require optional external tools or a wrapper service. They are outside V1 unless included in the standalone bundle later.
• Artist URLs may require interactive selection in gamdl; V1 is intended primarily for direct song, album, and playlist URLs.
• Large downloads are loaded into n8n binary storage through the standard helper and may require appropriate n8n binary-data/storage configuration.

Only download media you are authorized to access and use. You are responsible for complying with applicable laws and service terms.

License

MIT. Bundled gamdl artifacts must retain gamdl's license and the licenses/notices of all included dependencies.