cloudspin 0.1.0__py3-none-any.whl

cloudspin-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: cloudspin
+Version: 0.1.0
+Summary: A terminal music player that lives under a living sky: spinning vinyl, real weather, animated scenes.
+Project-URL: Homepage, https://github.com/itsHarshDabas/Cloudspin
+Project-URL: Issues, https://github.com/itsHarshDabas/Cloudspin/issues
+Author: Harsh Dabas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mpv,music,player,terminal,textual,tui,weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Requires-Python: >=3.11
+Requires-Dist: mutagen>=1.47
+Requires-Dist: pillow>=10.0
+Requires-Dist: textual>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cloudspin
+
+A music player for your terminal that lives under a sky. A record spins, the
+weather for your city is written across the horizon, and the sky itself changes
+with the song: phonk brings a thunderstorm, lo-fi settles into evening,
+synthwave turns the stars on.
+
+![Cloudspin playing a lo-fi song under an evening sky](https://raw.githubusercontent.com/itsHarshDabas/Cloudspin/main/docs/evening.png)
+
+| Phonk gets a storm | Synthwave gets the night, in the cover's colours |
+| --- | --- |
+| ![Thunderstorm scene](https://raw.githubusercontent.com/itsHarshDabas/Cloudspin/main/docs/storm.png) | ![Night scene](https://raw.githubusercontent.com/itsHarshDabas/Cloudspin/main/docs/night.png) |
+
+## What it does
+
+- Plays local files, folders, radio streams and links through `mpv`.
+- Paste a link while it's running (press `o`) and it starts playing.
+- Shows live weather and a six-day forecast from [Open-Meteo](https://open-meteo.com) (free, no API key).
+- Draws an animated sky: sun, moon with the real phase, stars, drifting clouds, rain, snow, fog and lightning.
+- Picks the sky to suit the song, or follows the real weather, or stays on a scene you pin.
+- Takes its colours from the sky, from the song's cover art, or from a theme you write.
+- Spins a record whose label is the album cover, with a tonearm that tracks through the song.
+- Works with the mouse: click the buttons, drag the progress line, click a song in Up next, scroll for volume.
+
+## Install
+
+Cloudspin is not on PyPI, the AUR or npm yet. Until it is, install it from this repository:
+
+```sh
+pipx install git+https://github.com/itsHarshDabas/Cloudspin
+# or
+uv tool install git+https://github.com/itsHarshDabas/Cloudspin
+```
+
+You also need `mpv` for sound. Two more tools are optional:
+
+| Tool | Why |
+| --- | --- |
+| `mpv` | Plays the music. Without it Cloudspin runs silently. |
+| `ffmpeg` | Lets Cloudspin listen to songs that have no genre tag, to guess a sky. |
+| `yt-dlp` | Lets mpv play YouTube, SoundCloud and similar links. |
+
+On Arch: `sudo pacman -S mpv ffmpeg yt-dlp`.
+
+Needs Python 3.11 or newer, Linux or macOS, and a terminal with truecolor
+(kitty, foot, Alacritty, WezTerm, Ghostty, iTerm2 and most others).
+
+## Use
+
+```sh
+cloudspin                       # plays ~/Music
+cloudspin ~/Music/phonk         # a folder
+cloudspin song.flac other.mp3   # files
+cloudspin https://example.com/stream.mp3   # a link
+cloudspin --city "New Delhi"    # set the city once; it is remembered
+cloudspin --demo                # look around without any music or sound
+```
+
+### Keys
+
+| Key | Does |
+| --- | --- |
+| `space` | Play or pause |
+| `n` `p` | Next song, previous song |
+| `←` `→` | Skip 5 seconds (`Shift` for 30) |
+| `+` `-` | Volume |
+| `s` | Shuffle |
+| `r` | Repeat: off, all, one |
+| `o` | Open a link, file or folder and play it |
+| `w` | Sky: follow the song, follow the weather, or pin a scene |
+| `t` | Colours: follow the sky, follow the cover art, or a theme |
+| `c` | Choose the city |
+| `u` | Switch °C and °F |
+| `?` | Show the keys |
+| `q` | Quit |
+
+## How the sky picks a scene
+
+With the sky set to follow the song (the default), Cloudspin looks for a
+scene in this order and uses the first one it finds:
+
+1. **Your rules.** Words you map to scenes in the config file.
+2. **The tags.** The genre tag, then sky words in the title or album.
+   `phonk`, `metal` and `dubstep` storm; `lofi`, `jazz` and `acoustic` get the
+   evening; `synthwave` and `r&b` get the night; `blues` rains; `dream pop`
+   fogs over; `christmas` snows; `pop` and `dance` get a sunny day. A song
+   called "Midnight Rain" needs no tag at all.
+3. **A short listen.** If `ffmpeg` is installed, 30 seconds of the song are
+   measured for loudness, tempo, bass and brightness. Loud, fast and
+   bass-heavy becomes a storm; quiet and slow becomes night.
+4. **The real weather**, if nothing above says anything.
+
+The caption in the top right corner of the sky always says which scene is
+showing and why, for example `Thunderstorm, tagged Drift phonk`.
+
+The scenes are `storm`, `rain`, `evening`, `night`, `day`, `dawn`, `snow`,
+`fog` and `overcast`.
+
+## Settings
+
+Settings live in `~/.config/cloudspin/config.toml`. Everything is optional.
+
+```toml
+city = "New Delhi"
+units = "metric"      # or "imperial"
+sky = "song"          # "song", "weather", or a scene name to pin
+colors = "sky"        # "sky", "cover", a built-in theme, or one of yours
+music = "~/Music"
+volume = 70
+fps = 24              # lower this on a slow terminal or over SSH
+
+# Send particular artists, albums or words to a scene.
+[moods]
+"kordhell" = "storm"
+"study mix" = "evening"
+
+# Your own colours. Only `accent` is required.
+[themes.neon]
+accent = "#39ff88"
+accent2 = "#00c2ff"
+background = "#07100c"
+disc = "#39ff88"      # the record label, when the song has no cover art
+disc2 = "#ffffff"
+```
+
+Built-in themes: `sky`, `cover`, `amber`, `orchid`, `lagoon`, `moss`, `rose`, `mono`.
+
+## Good to know
+
+- **The bars are generative.** The spectrum moves with the play state, the
+  volume and a tempo chosen per song. It is not a live analysis of the audio.
+- **The listen is a guess.** Step 3 above is a heuristic that has only been
+  checked against synthetic test audio. Tags and your own rules are exact;
+  use `[moods]` when it gets a song wrong.
+- **Links need mpv.** Plain audio URLs and radio streams work with mpv alone.
+  Sites like YouTube also need `yt-dlp`.
+- **Windows is not supported** except through WSL: playback control uses a
+  Unix socket.
+- **MPRIS** (media keys, `playerctl`, Waybar) works if you have the
+  `mpv-mpris` plugin installed for mpv; Cloudspin loads your normal mpv config.
+
+## Packaging status
+
+| Channel | Status |
+| --- | --- |
+| Git (`pipx`, `uv`) | Works today |
+| PyPI and npm | Published by `.github/workflows/release.yml` when a `v*` tag is pushed. Setup steps are at the top of that file. |
+| AUR | `packaging/aur/PKGBUILD` is written; it builds from the PyPI release |
+| Homebrew | Not started |
+
+The npm package is a small launcher that runs the Python app through `uv` or `pipx`.
+
+## Develop
+
+```sh
+git clone https://github.com/itsHarshDabas/Cloudspin && cd Cloudspin
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python scripts/screenshot.py out.png --song 2   # render the app to a PNG, no terminal needed
+```
+
+The code is small and split by job:
+
+| File | Job |
+| --- | --- |
+| `sky.py` | The procedural sky and landscape |
+| `canvas.py` | Half-block pixel drawing |
+| `vinyl.py`, `spectrum.py` | The record and the bars |
+| `mood.py` | Choosing a scene for a song |
+| `weather.py` | Open-Meteo and sun and moon maths |
+| `player.py` | mpv control and the queue |
+| `widgets.py`, `app.py` | The interface |
+
+## Licence
+
+MIT

cloudspin-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+cloudspin/__init__.py,sha256=aQ5kyLuD1RcYczbKvN99YlgBE72RF03fGw1wO6Azkes,95
+cloudspin/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+cloudspin/app.py,sha256=hZAZFSfA536dxOczf_hFaNwRbROYzxExrTUD_tsUmdc,19763
+cloudspin/canvas.py,sha256=Kz-aapw_5CoDGTZyKFR1Txv1ZL4ZtuVI1j7QzUSnfCw,11455
+cloudspin/cli.py,sha256=FQy6Fj5JCbNbkRdSQnZmussGX_4BF9FLwI7rX4iVSKE,3954
+cloudspin/color.py,sha256=ZgVPwITBhKgDgPFP7fEDgmsI4EiQmQ3xIJijuetJKbI,2295
+cloudspin/config.py,sha256=WAV4pAUTlqJkympm0JVYL1F_8859ASoj-i1REKERfnY,4060
+cloudspin/library.py,sha256=cNbsnDHcCoFsIHuHjdNtnC0wxlnt_Z2_E3-GqDV-YkY,4546
+cloudspin/mood.py,sha256=yBhe9oLngLtkl4g_-9Dq98Lz6f16g0LDAXhkS4t6Cbk,10152
+cloudspin/player.py,sha256=GJPNg83mqOFBjhXFgFTFU_Qd6G3OYOOFugbnKbVfJ2U,15233
+cloudspin/screens.py,sha256=OBMC_7uuaMYWN4apXRlrlD04lqRQrcVAxFI3EmzCW9c,3900
+cloudspin/sky.py,sha256=qtx3BG7axHfanJBVev_MFsKBceXw4tPvGzsQt6cqD4o,33939
+cloudspin/songlook.py,sha256=wxMYmQHLkTvOlv_QEbsDWCf0xlNKl9fkUyg67O5UCm8,3982
+cloudspin/spectrum.py,sha256=30CLB3fEjmfM7vr0EaMJ4_njJmLRlwgr810zTT5W6OU,3057
+cloudspin/themes.py,sha256=ghPsmtKPlLVaVTmbnhoSp3_l-els95zlk6eHa5yagY8,3200
+cloudspin/vinyl.py,sha256=dbNAR5u7ObZxYU6vksgAsyyTLLhHt4Cpyvt7YIVFlDI,7638
+cloudspin/weather.py,sha256=xt03r904ikPR3VUdfJe-7UlE1cP9gmXxVPX-1nNYzBY,12235
+cloudspin/widgets.py,sha256=jlo21ZU9d0mmbn4LQ7ky77yxleccAMTB-rCTpLuEnyM,28105
+cloudspin-0.1.0.dist-info/METADATA,sha256=Z2M4ZKCC3n8bXvOZt7HW868kHT3gweaX4MNUAq7e5Xk,7905
+cloudspin-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cloudspin-0.1.0.dist-info/entry_points.txt,sha256=ns7ZSSAW3RSDnxtj5F0si85ZyGwny9QnByU-HvCMOy4,49
+cloudspin-0.1.0.dist-info/licenses/LICENSE,sha256=mMoe-B3GqNGxc65D1KctAN6g5mp8w71QaS6dD3A8akM,1068
+cloudspin-0.1.0.dist-info/RECORD,,

cloudspin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cloudspin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cloudspin = cloudspin.cli:main

cloudspin-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harsh Dabas
+
+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.