Metadata-Version: 2.4
Name: addsong
Version: 1.0.1
Summary: Download a song from a URL or YouTube search and auto-import it into Apple Music.
Project-URL: Homepage, https://github.com/ado11231/addsong
Project-URL: Source, https://github.com/ado11231/addsong
Project-URL: Issues, https://github.com/ado11231/addsong/issues
Author: Adnan Alagic
License: MIT License
        
        Copyright (c) 2026 Adnan Alagic
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: apple-music,cli,ffmpeg,music,yt-dlp
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

<h3 align="center">addsong</h3>

<p align="center">
  <a href="https://pypi.org/project/addsong/"><img src="https://img.shields.io/pypi/v/addsong.svg?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/pypi/pyversions/addsong.svg?style=for-the-badge&logo=python&logoColor=yellow" alt="Python versions"></a>
  <a href="https://github.com/ado11231/addsong/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/addsong.svg?style=for-the-badge&color=green" alt="License"></a>
  <a href="https://github.com/yt-dlp/yt-dlp"><img src="https://img.shields.io/badge/Powered%20by-yt--dlp-FF0000.svg?style=for-the-badge&logo=youtube&logoColor=white" alt="Powered by yt-dlp"></a>
  <a href="https://ffmpeg.org/"><img src="https://img.shields.io/badge/Tagged%20with-ffmpeg-007808.svg?style=for-the-badge&logo=ffmpeg&logoColor=white" alt="Tagged with ffmpeg"></a>
</p>

<p align="center">
  <img src="assets/demo.gif" alt="addsong demo" width="600">
</p>

<p align="center"><b>Paste a link and the song shows up in Apple Music.</b></p>

addsong takes a song name or a YouTube link. It downloads the track, tags it
with the title, artist, and cover art, then drops it into Apple Music. No
dragging files around, just a single command.

```bash
addsong "songname"
addsong "https://www.youtube.com/watch?v=..."
```

## Installation

You need Python 3.11 or newer, plus two tools that do the real work, yt-dlp
and ffmpeg. addsong itself is a Python package you install with pipx.

### 1. Install addsong

```bash
pipx install addsong
```

Don't have pipx yet? Install it first. On macOS run `brew install pipx`. On
Linux run `pip install --user pipx` (or use your distro's package). On Windows
run `pip install pipx`. Once pipx is set up, run `pipx ensurepath` and reopen
your terminal so addsong is on your PATH.

No pipx? `pip install --user addsong` works too.

### 2. Install yt-dlp and ffmpeg

These do the downloading and tagging. Pick the command for your system.

&nbsp;<img src="assets/macos.svg" height="22" align="absmiddle" style="position: relative; top: -3px;"> **macOS**

```bash
brew install yt-dlp ffmpeg
```

&nbsp;<img src="assets/linux.svg" height="22" align="absmiddle" style="position: relative; top: -3px;"> **Linux and WSL**

```bash
sudo apt-get install -y ffmpeg && pipx install yt-dlp
```

On other distros use your package manager for ffmpeg. yt-dlp can come from
pipx or pip.

&nbsp;<img src="assets/windows.svg" height="22" align="absmiddle" style="position: relative; top: -3px;"> **Windows** (PowerShell)

```powershell
winget install yt-dlp.yt-dlp Gyan.FFmpeg
```

### 3. Check it

```bash
addsong --version
```

## Updating

```bash
pipx upgrade addsong
```

With pip instead of pipx, run `python -m pip install --user --upgrade addsong`.

## Shell Completions

addsong can print a completion script for your shell. Source it or save it to
your shell's completion directory.

```bash
source <(addsong --print-completion bash)      # bash
addsong --print-completion zsh  > ~/.zsh/completions/_addsong   # zsh
addsong --print-completion fish > ~/.config/fish/completions/addsong.fish  # fish
```

See your shell's docs for where completion files go.

## Your First Song

```bash
addsong "songname"
```

addsong shows what it found so you can fix mistakes before saving.

```
  Review track ♪
  Artist: Artist Name
  Title:  Song Title

  [Enter] Add  ·  [E] Edit  ·  [S] Skip
  ❯
```

Press Enter and the song lands in Apple Music a second later.

## Commands


| Command                        | What it does                                    |
| ------------------------------ | ----------------------------------------------- |
| `addsong "name"`               | Add the top search result                       |
| `addsong "<link>"`             | Add a specific video                            |
| `addsong --results 3 "name"`   | Add the top 3 search results                    |
| `addsong --playlist "<link>"`  | Add a whole playlist                            |
| `addsong --from list.txt`      | Add every link in a file                        |
| `addsong subscribe "<link>"`   | Follow a playlist                               |
| `addsong sync`                 | Add new songs from playlists you follow         |
| `addsong list`                 | Show playlists you follow                       |
| `addsong unsubscribe "<link>"` | Stop following a playlist                       |
| `addsong forget`               | Forget everything added so it can be re-added   |



## Flags


| Flag                    | What it does                                           |
| ----------------------- | ------------------------------------------------------ |
| `-y`                    | Don't ask, just add it                                 |
| `--review`              | Always pause to fix the title or artist first          |
| `--reimport`            | Add a song again even if you already have it           |
| `--dry-run`             | Show what would happen without downloading            |
| `--format FMT`          | Output format, `m4a` (default), `mp3`, `flac`, `opus`  |
| `--quality N`           | Audio quality 0 to 10, 0 is best and the default       |
| `--notify`              | Pop a desktop notification as each song imports        |
| `--quiet` / `--verbose` | Show less or more output                               |
| `--help`                | Full list of commands and options                      |


Set environment variables like `ADDSONG_WATCH_DIR` to change defaults. Run
`addsong --help` for the full list.

## Download Location

On macOS and Windows songs go straight into Apple Music. On Linux they land
in `~/Music/addsong/`. Point them somewhere else with
`ADDSONG_WATCH_DIR=/your/folder`.

## Common Errors

If you see `command not found`, run `pipx ensurepath` and reopen your
terminal. Still stuck? Repeat the [Installation](#installation) step.

If a song downloads but never shows up, open the Apple Music app and keep it
open while adding (macOS or Windows).

If a download fails, update yt-dlp, then retry with `--verbose` to see why.