osp-tools

python tools for managing openswim mp3 players.

cli overview

features

• device detection: automatically finds openswim device path on macos, linux, and windows.
• youtube: downloads audio via yt-dlp wrapper. supports videos, playlists, shorts.
• spotify: scrapes track metadata without api keys. supports tracks, albums, playlists, artist top tracks.
• bulk: threaded processing for multiple queries.

installation

pip (recommended)

pip install osp-tools

manual build

git clone https://github.com/1etu/osp-tools.git
cd osp-tools
pip install build
python -m build
pip install dist/osp_tools-*.whl

development

git clone https://github.com/1etu/osp-tools.git
cd osp-tools
pip install -e ".[dev]"

usage

osp --help

device management

osp device              # show device info, storage usage
osp ls                  # list tracks on device

youtube download

osp dl "https://youtube.com/watch?v=..."             # download single video
osp dl "https://youtube.com/playlist?list=..."       # download entire playlist
osp dl dQw4w9WgXcQ                                   # download by video id
osp dl "..." --device                                # download directly to openswim
osp dl "..." -f m4a                                  # download as m4a (more efficient)
osp dl "..." -f mp3 -q 320                          # 320kbps mp3
osp dl "..." -f flac                                 # lossless audio (flac)
osp dl "..." -o ./music                              # custom output directory

youtube search

osp search "song name"                # search youtube, get video ids
osp search "artist - track" -n 10     # limit results

spotify (no api keys)

osp spotify "https://open.spotify.com/track/..."     # single track
osp spotify "https://open.spotify.com/album/..."     # full album
osp spotify "https://open.spotify.com/playlist/..."  # playlist
osp spotify "https://open.spotify.com/artist/..."    # artist top tracks
osp spotify "..." --info                             # show track list only
osp spotify "..." --device                           # download to openswim
osp spotify "..." -f m4a                             # download as m4a
osp spotify "..." -f mp3 -q 320                      # 320kbps mp3
osp spotify "..." -w 8                               # 8 parallel downloads
osp spotify "..." --fast                             # skip transcoding (~2x speed)
osp spotify "..." -f m4a --fast                      # m4a + fast mode (fastest)

sync local files

osp sync ./downloads              # sync folder to device (skip existing)
osp sync ./downloads --all        # overwrite all

format support

supported formats: mp3, m4a, aac, flac, opus, wav, ogg

format quality ranges (auto-adjusted):

• mp3: 128-320kbps (default: 192)
• m4a/aac: 96-256kbps (default: 160, more efficient)
• opus: 96-320kbps (default: 160)
• ogg: 128-320kbps (default: 192)
• flac/wav: lossless (quality ignored)

dependencies

• python 3.9+
• yt-dlp
• ffmpeg (for audio conversion)

structure

• osp/core: device discovery and mount point logic.
• osp/download: youtube/spotify scrapers and downloaders.

license

MIT