The scraper stops after 5 consecutive scrolls with no new posts, or after a
3-minute timeout (partial results are returned if any were found). Large
collections may be rate-limited by Instagram.

## Support the Project

If ArcDLP is useful to you, consider supporting development:

- [Sponsor on GitHub](https://github.com/sponsors/archisvaze)
- [Buy Me a Coffee](https://buymeacoffee.com/archisvaze)

---

## For Developers

Everything below is for people who want to build from source, modify the app, or
contribute.

### Contributing

Contributions are welcome. The codebase is intentionally simple - no frameworks,
no build tools, vanilla JS throughout.

Before making changes, read through the code and match existing patterns. A few
principles the project follows:

- **Keep it simple.** If something can be done in 30 lines, don't use a library.
- **Resilience first.** One failure should never kill the queue. Users should
always know what's happening.
- **Explicit actions only.** No auto-fetching, no auto-retrying. Every action
traces to a button click.
- **Let yt-dlp do the work.** Don't reimplement what yt-dlp already handles. The
app is a GUI wrapper, not a competing tool.
- **Multi-site compatibility.** Never assume YouTube-specific behavior unless
explicitly scoped. Format detection, error handling, and UI labels should work
for any site yt-dlp supports.

#### Getting Started

1. Fork and clone the repo
2. `npm install` (downloads yt-dlp + ffmpeg automatically) - See details below
for Windows and Linux install
3. `npm run dev` to launch with DevTools - See more details below
4. Make your changes, test across a few different sites
5. Open a PR with a clear description of what changed and why

### Build from Source

```bash
git clone https://github.com/archisvaze/arcdlp.git
cd arcdlp
npm install
```

#### Cross-platform builds

Both `ffmpeg-static` and the yt-dlp postinstall script download platform-specific
binaries during `npm install`. On macOS, this works automatically, no setup needed.

If you're building for a different architecture (e.g. building the Linux x64
AppImage from an ARM machine), set these environment variables **before**
`npm install` to ensure the correct binaries are downloaded:

**Windows (x64):**

$env:npm_config_platform = "win32"
$env:npm_config_arch = "x64"
rm -r -Force node_modules
npm install

**Linux (x64):**

export npm_config_platform=linux
export npm_config_arch=x64
rm -rf node_modules bin
npm install

Only one binary per platform is downloaded per install. If you need to switch
target architectures, delete `node_modules` and `bin` and run `npm install`
again with the new env vars.

### Development

```bash
npm run dev # macOS / Linux
npm run dev:win # Windows
```

This launches the app with DevTools enabled and verbose logging.

### Production Builds

```bash
npm run build:mac # macOS - produces .dmg and .zip
npm run build:win # Windows - produces NSIS installer
npm run build:linux # Linux - produces AppImage
npm run build:all # All platforms
```

Both yt-dlp and ffmpeg binaries are bundled into the built app via
`extraResources` in package.json.

### Project Structure

```
arcdlp/
├── src/
│ ├── main/
│ │ ├── main.js # Electron main process, IPC, window, history
│ │ ├── preload.js # Context bridge (window.api)
│ │ ├── ytdlp.js # yt-dlp integration: spawn, parse, download
│ │ ├── queue.js # Sequential download queue with per-item state
│ │ ├── cookies.js # YouTube + Instagram cookie auth
│ │ ├── scraper.js # Instagram collection scraper (BrowserWindow)
│ │ ├── updater.js # Update checker via GitHub Releases API
│ │ └── utils.js # Dev mode flag, logging helpers
│ └── renderer/
│ ├── index.html # UI structure
│ ├── renderer.js # UI logic, state, rendering
│ └── index.css # All styles
├── scripts/
│ ├── postinstall.js # Downloads yt-dlp binary on npm install
│ └── fix-ffmpeg-win.js # Renames ffmpeg for Windows builds
├── bin/ # yt-dlp binary (auto-populated by postinstall)
├── build/ # App icons (icon.icns, icon.ico, icon.png)
├── package.json
├── LICENSE
└── README.md
```

### How It Works

1. User pastes a URL and clicks Fetch
2. App spawns `yt-dlp --dump-json` to get video metadata and available formats
3. User picks a quality preset or audio extraction
4. Click "Add to Queue" - the download is queued and processed sequentially
5. yt-dlp handles the actual download with `--progress-template` for structured
progress output
6. Completed files are saved to the configured download folder

For playlists, the app uses `--flat-playlist --dump-json` to stream items one at
a time, then queues selected items for download.

### Dependencies

Only two runtime dependencies:

- **electron-store** - Persistent settings and history
- **ffmpeg-static** - Bundled ffmpeg binary for audio extraction and format
merging

Dev dependencies: `electron`, `electron-builder`.

yt-dlp handles all downloading, format selection, and ffmpeg orchestration
internally. The app is a GUI wrapper around it.

### Roadmap

ArcDLP covers the core download workflow, but yt-dlp has a huge feature set that
could be surfaced in the GUI. Here's what's planned and where contributors can
help.

#### Quality of Life

- ~~**Thumbnails in playlist items** - The data is already fetched, just not
rendered yet~~ _(completed in v1.2.3)_
- **File size estimates** - Show approximate size on quality presets when
available
- **Download complete notification** - System notification when the queue
finishes (only if window is not focused)
- **Playlist fetch cancellation** - Currently can't cancel a playlist fetch
mid-way through
- **Verbose log toggle** - Clean messages by default, raw yt-dlp output when
debugging

#### Advanced yt-dlp Features

yt-dlp supports a lot more than basic downloading. These features would make
great contributions:

- **Subtitle downloads** - `--write-subs`, `--sub-langs`, language selection UI
- **Embed metadata** - `--embed-thumbnail`, `--embed-metadata` for tagging files
- **SponsorBlock integration** - `--sponsorblock-remove`, `--sponsorblock-mark`
to skip or mark sponsored segments
- **Additional audio formats** - AAC, FLAC, WAV, Opus extraction (currently MP3
only)
- **Format filtering** - Expose yt-dlp's format selection syntax for advanced
users
- **Download archive** - `--download-archive` to skip already-downloaded videos
- **Rate limiting** - `--limit-rate` for bandwidth control
- **Proxy support** - `--proxy` for users behind restrictive networks
- **Custom output templates** - `--output` template configuration in settings
- **Chapter splitting** - `--split-chapters` to save individual chapters as
separate files

#### App-Level Features

- **Keyboard shortcuts** - Quick access to common actions
- **More site-specific auth** - Expand the cookie login flow to more sites
beyond YouTube and Instagram
- **Playlist detection for more sites** - Currently conservative (YouTube,
SoundCloud, and Instagram saved collections)
- **DOM virtualization for large playlists** - Currently renders all items,
works fine under ~1000

#### Known Cleanup Items

- `video:fetch` IPC returns the full raw JSON (50-200KB) even in production -
should be dev-only
- Queue `_items` array has no upper bound - consider a cap or auto-clear
- Playlist checkbox uses inline `onchange` handler - could use event delegation
- Log type detection is greedy (`msg.includes('complete')` matches "incomplete")

## License

[MIT](LICENSE)

## Credits