moved docs around

2026-10-02 00:30:02 -07:00
parent 6f1d839e6a
commit 8b4cfc0cb9
3 changed files with 190 additions and 173 deletions
@@ -79,171 +79,6 @@ _(written by LLM, cleaned up by me)_
 ## Sharing music with friends (Cassette)
 Cassette lets you subscribe to friends' playlists, peek at their libraries and download their songs via a program called **Syncthing**.
 ### 1. Install and start Syncthing (once)
 Open a terminal and paste the line for your distro:
 ```sh
 sudo apt install syncthing        # Debian / Ubuntu / Mint
 sudo dnf install syncthing        # Fedora
 ```
 Then start it, and have it start by itself every time you log in:
 ```sh
 systemctl --user enable --now syncthing
 ```
 To check it's running, open <http://127.0.0.1:8384> in your web browser —
 you should see Syncthing's page. You don't have to do anything there; the
 default settings (including "global discovery" and "relaying", which let two
 computers find each other across the internet) are exactly right.
 > **Already using Syncthing to keep your library on two of your own
 > computers?** Great — nothing changes. Only one of your computers handles
 > friends; LinTunes asks which the first time (see below), and songs it brings
 > in reach your other computers the usual way.
 ### 2. Connect with a friend
 One of you **invites**, the other **pastes**. It doesn't matter who.
 **If you're inviting:** in LinTunes choose **Connections ▸ Share Library with a
 Friend…**. The very first time, LinTunes asks *"Use this computer for sharing
 with friends?"* — say **Yes**. You'll get an **invite code**: a long line
 starting with `LTC1.` Press **Copy Code** and send it to your friend however you
 like (text, email, chat). Each code works for **one** friend, once.
 **If you were sent a code:** choose **Connections ▸ Add Friend Library…**,
 paste the whole code into the box, and press **Connect**.
 That's it. When the two computers have found each other, you'll see
 **"*Name* is now connected."** at the bottom of the window. This can take a
 minute — or, if the other computer is off, however long until it's back on.
 You can see how it's going any time in **Connections ▸ Sync Settings…**: pick
 your friend in the list on the left. Invites nobody has used yet are listed on
 the **General** page, with a **Cancel Invite** button each.
 ### 3. Choose what your friend can see
 **Nothing is shared until you say so.** In **Connections ▸ Sync Settings…**,
 click your friend's name on the left. Below their connection status are two
 sections:
 - **Library** — tick the artists, albums or songs your friend may ask for, or
  tick **Share whole library** for everything (including songs you add later).
 - **Playlists** — tick the playlists to share, or **Share all playlists**.
  A shared playlist brings its songs along: they show up ticked and greyed in
  the Library section (hover one to see which playlist is holding it there).
 **Select All** and **Select None** do what they say — and if you click one by
 accident, just press **Cancel**: nothing is saved until you press **OK**.
 Want everyone to see the same thing? On the **General** page, tick **Share the
 same selection with all friends** and choose there instead.
 Sharing something doesn't send it. Your friend only receives what they ask
 for.
 ### 4. Browse a friend's library and ask for songs
 Once you have a friend, a small **▾** appears on the right end of the
 **Library** button:
 <img src="docs/cassette/library-selector.png" alt="The Library button with the ▾ friend selector on its right" width="216">
 Click the **▾** and pick your friend. The button turns light purple and shows
 their library's name — you're now looking at what they've shared with you:
 <img src="docs/cassette/friend-library-button.png" alt="The Library button in friend mode, purple, reading Sam's Library" width="216">
 ![Browsing a friend's library](docs/cassette/friend-mode.png)
 It works just like your own library, except nothing plays (the songs aren't on
 your computer yet). Instead, every artist, album and song has a little
 **cassette button**:
 | Button | What it means |
 |---|---|
 | <img src="docs/cassette/cassette-off.png" width="28" alt="cassette button, not pressed"> | Not asked for. Click it to ask your friend for this. |
 | <img src="docs/cassette/cassette-on.png" width="28" alt="cassette button, pressed"> | Asked for — this song is on its way to you. Click again to change your mind. |
 | <img src="docs/cassette/cassette-partial.png" width="28" alt="cassette button, partly pressed"> | Some of this artist's or album's songs are asked for. Click to ask for all of them. |
 Pressing the button on an **artist** or **album** asks for every song under it.
 Along the bottom of the window:
 - **Hide tracks I have** hides songs you already own. Songs that are *probably*
  the same as one of yours (same artist and title, different album or length)
  stay visible in light grey so you can decide.
 - The **size** of what you've asked for, next to your free space. It turns
  **orange** if it would leave so little space that Syncthing pauses, and
  **red** if it won't fit at all.
 - **Save and Close** sends your list to your friend and takes you back to your
  own library. **Cancel** forgets the changes. (Leaving any other way with
  changes asks *"Save changes?"* first.)
 The songs you asked for arrive in your library **by themselves**, filed by
 artist and album like anything you'd add yourself, with *"3 songs arrived from
 Sam."* at the bottom of the window. They come with their names, album info and
 artwork — but not your friend's play counts or ratings.
 ### 5. Follow a friend's playlist
 In a friend's library, their shared playlists are listed on the left, each
 with a UFO. Click a playlist's **UFO** to follow it:
 | Icon | What it means |
 |---|---|
 | <img src="docs/cassette/ufo-not-followed.png" width="28" alt="grey outline UFO"> | Not following. Click the UFO to follow this playlist. |
 | <img src="docs/cassette/ufo-followed.png" width="28" alt="purple UFO"> | Following. Click again to stop. |
 Press **Save and Close**, and the playlist appears in **your** sidebar with a
 purple UFO, and plays like any other playlist:
 ![A followed playlist in the sidebar](docs/cassette/followed-playlist.png)
 - Songs that are still on their way show in grey; they become playable as they
  arrive. The bottom of the window says when your friend's folder last synced.
 - A followed playlist's songs are **kept separate from your library** — you get
  to listen without them filling up your collection. Like one? Right-click the
  column headings, turn on **Cassette**, and press its cassette button to add
  it to your library.
 - Right-click a followed playlist in the sidebar and choose **Unfollow** to let
  it go (its songs are cleaned up afterwards).
 Two choices per friend, in **Sync Settings** on their page:
 - Show followed playlists **mixed in with yours**, or grouped **in a folder
  with their name**.
 - **Keep their songs separate** (the default), or **add them to your library**
  automatically.
 ### If something isn't working
 Sync Settings always says what's going on in plain words and what to do next.
 The common ones:
 - **"Syncthing isn't running"** — run `systemctl --user start syncthing`, then
  press **Retry** on the General page.
 - **"Can't reach Syncthing's API"** — press **Read from Syncthing** on the
  General page. (Or copy the key from Syncthing's page at
  <http://127.0.0.1:8384>: **Actions ▸ Settings ▸ General ▸ API Key**.)
 - **"Waiting for *Name*'s computer"** for a long time — both computers need to
  be on with Syncthing running, and your friend needs to have opened LinTunes
  once since you pasted the code. If it never connects, the code may already
  have been used: ask for a new one.
 - **"That code isn't valid"** — part of the code got lost when it was copied.
  It's one long line starting with `LTC1.`; ask your friend to send it again.
 - **"This invite has already been used"** — codes work once. Ask for a new one.
 To stop sharing with someone, open their page in Sync Settings and press
 **Remove Friend…**. Songs you already brought into your library stay.
@@ -313,15 +148,9 @@ _(written by LLM and cleaned up a bit by me)_
  something you'd care about happened.
 **Sharing with friends (Cassette)**
- Share parts of your library with a friend — one pasted code connects you,
+- Share playlists with friends! More info at [cassette.md](cassette.md)
-  over [Syncthing](https://syncthing.net), with no server anywhere.
+
 - You choose exactly what each friend can see: the whole library, or just
  certain artists, albums, songs and playlists.
 - Browse a friend's library and press the little cassette buttons on anything
  you'd like; those songs arrive in your library by themselves.
 - Follow a friend's playlist and play it right from your own sidebar.
 \
 # BUT WAIT, THERE'S MORE
@@ -0,0 +1,166 @@
 ## Sharing music with friends (Cassette)
 Cassette lets you subscribe to friends' playlists, peek at their libraries and download their songs via a program called **Syncthing**.
 ### 1. Install and start Syncthing (once)
 Open a terminal and paste the line for your distro:
 ```sh
 sudo apt install syncthing        # Debian / Ubuntu / Mint
 sudo dnf install syncthing        # Fedora
 ```
 Then start it, and have it start by itself every time you log in:
 ```sh
 systemctl --user enable --now syncthing
 ```
 To check it's running, open <http://127.0.0.1:8384> in your web browser —
 you should see Syncthing's page. You don't have to do anything there; the
 default settings (including "global discovery" and "relaying", which let two
 computers find each other across the internet) are exactly right.
 > **Already using Syncthing to keep your library on two of your own
 > computers?** Great — nothing changes. Only one of your computers handles
 > friends; LinTunes asks which the first time (see below), and songs it brings
 > in reach your other computers the usual way.
 ### 2. Connect with a friend
 One of you **invites**, the other **pastes**. It doesn't matter who.
 **If you're inviting:** in LinTunes choose **Connections ▸ Share Library with a
 Friend…**. The very first time, LinTunes asks *"Use this computer for sharing
 with friends?"* — say **Yes**. You'll get an **invite code**: a long line
 starting with `LTC1.` Press **Copy Code** and send it to your friend however you
 like (text, email, chat). Each code works for **one** friend, once.
 **If you were sent a code:** choose **Connections ▸ Add Friend Library…**,
 paste the whole code into the box, and press **Connect**.
 That's it. When the two computers have found each other, you'll see
 **"*Name* is now connected."** at the bottom of the window. This can take a
 minute — or, if the other computer is off, however long until it's back on.
 You can see how it's going any time in **Connections ▸ Sync Settings…**: pick
 your friend in the list on the left. Invites nobody has used yet are listed on
 the **General** page, with a **Cancel Invite** button each.
 ### 3. Choose what your friend can see
 **Nothing is shared until you say so.** In **Connections ▸ Sync Settings…**,
 click your friend's name on the left. Below their connection status are two
 sections:
 - **Library** — tick the artists, albums or songs your friend may ask for, or
  tick **Share whole library** for everything (including songs you add later).
 - **Playlists** — tick the playlists to share, or **Share all playlists**.
  A shared playlist brings its songs along: they show up ticked and greyed in
  the Library section (hover one to see which playlist is holding it there).
 **Select All** and **Select None** do what they say — and if you click one by
 accident, just press **Cancel**: nothing is saved until you press **OK**.
 Want everyone to see the same thing? On the **General** page, tick **Share the
 same selection with all friends** and choose there instead.
 Sharing something doesn't send it. Your friend only receives what they ask
 for.
 ### 4. Browse a friend's library and ask for songs
 Once you have a friend, a small **▾** appears on the right end of the
 **Library** button:
 <img src="docs/cassette/library-selector.png" alt="The Library button with the ▾ friend selector on its right" width="216">
 Click the **▾** and pick your friend. The button turns light purple and shows
 their library's name — you're now looking at what they've shared with you:
 <img src="docs/cassette/friend-library-button.png" alt="The Library button in friend mode, purple, reading Sam's Library" width="216">
 ![Browsing a friend's library](docs/cassette/friend-mode.png)
 It works just like your own library, except nothing plays (the songs aren't on
 your computer yet). Instead, every artist, album and song has a little
 **cassette button**:
 | Button | What it means |
 |---|---|
 | <img src="docs/cassette/cassette-off.png" width="28" alt="cassette button, not pressed"> | Not asked for. Click it to ask your friend for this. |
 | <img src="docs/cassette/cassette-on.png" width="28" alt="cassette button, pressed"> | Asked for — this song is on its way to you. Click again to change your mind. |
 | <img src="docs/cassette/cassette-partial.png" width="28" alt="cassette button, partly pressed"> | Some of this artist's or album's songs are asked for. Click to ask for all of them. |
 Pressing the button on an **artist** or **album** asks for every song under it.
 Along the bottom of the window:
 - **Hide tracks I have** hides songs you already own. Songs that are *probably*
  the same as one of yours (same artist and title, different album or length)
  stay visible in light grey so you can decide.
 - The **size** of what you've asked for, next to your free space. It turns
  **orange** if it would leave so little space that Syncthing pauses, and
  **red** if it won't fit at all.
 - **Save and Close** sends your list to your friend and takes you back to your
  own library. **Cancel** forgets the changes. (Leaving any other way with
  changes asks *"Save changes?"* first.)
 The songs you asked for arrive in your library **by themselves**, filed by
 artist and album like anything you'd add yourself, with *"3 songs arrived from
 Sam."* at the bottom of the window. They come with their names, album info and
 artwork — but not your friend's play counts or ratings.
 ### 5. Follow a friend's playlist
 In a friend's library, their shared playlists are listed on the left, each
 with a UFO. Click a playlist's **UFO** to follow it:
 | Icon | What it means |
 |---|---|
 | <img src="docs/cassette/ufo-not-followed.png" width="28" alt="grey outline UFO"> | Not following. Click the UFO to follow this playlist. |
 | <img src="docs/cassette/ufo-followed.png" width="28" alt="purple UFO"> | Following. Click again to stop. |
 Press **Save and Close**, and the playlist appears in **your** sidebar with a
 purple UFO, and plays like any other playlist:
 ![A followed playlist in the sidebar](docs/cassette/followed-playlist.png)
 - Songs that are still on their way show in grey; they become playable as they
  arrive. The bottom of the window says when your friend's folder last synced.
 - A followed playlist's songs are **kept separate from your library** — you get
  to listen without them filling up your collection. Like one? Right-click the
  column headings, turn on **Cassette**, and press its cassette button to add
  it to your library.
 - Right-click a followed playlist in the sidebar and choose **Unfollow** to let
  it go (its songs are cleaned up afterwards).
 Two choices per friend, in **Sync Settings** on their page:
 - Show followed playlists **mixed in with yours**, or grouped **in a folder
  with their name**.
 - **Keep their songs separate** (the default), or **add them to your library**
  automatically.
 ### If something isn't working
 Sync Settings always says what's going on in plain words and what to do next.
 The common ones:
 - **"Syncthing isn't running"** — run `systemctl --user start syncthing`, then
  press **Retry** on the General page.
 - **"Can't reach Syncthing's API"** — press **Read from Syncthing** on the
  General page. (Or copy the key from Syncthing's page at
  <http://127.0.0.1:8384>: **Actions ▸ Settings ▸ General ▸ API Key**.)
 - **"Waiting for *Name*'s computer"** for a long time — both computers need to
  be on with Syncthing running, and your friend needs to have opened LinTunes
  once since you pasted the code. If it never connects, the code may already
  have been used: ask for a new one.
 - **"That code isn't valid"** — part of the code got lost when it was copied.
  It's one long line starting with `LTC1.`; ask your friend to send it again.
 - **"This invite has already been used"** — codes work once. Ask for a new one.
 To stop sharing with someone, open their page in Sync Settings and press
 **Remove Friend…**. Songs you already brought into your library stay.
@@ -1,3 +1,25 @@
 ## Importing an existing iTunes library
 In iTunes 12.x: **File ▸ Library ▸ Export Library** to get the XML, then:
 ```sh
 lintunes --import-xml "iTunes Library.xml" \
    --music-root "/path/to/iTunes Media" \
    --data-dir /path/to/library-data --save-config
 lintunes                                  # from now on, just run it
 ```
 This brings across your tracks, playlists, playlist folders and smart playlists
 (auto-updating and still editable), along with play counts, ratings and dates.
 Mac paths are remapped to `--music-root` automatically, including
 case/accent differences. Anything it couldn't find is written to
 `import_missing_files.txt` in your data dir. Untested on iTunes versions other
 than 12.
 ## Mac or Windows?
 LinTunes is only built and tested on Linux and