diff --git a/README.md b/README.md index 8626238..2091c8a 100644 --- a/README.md +++ b/README.md @@ -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 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: - -The Library button with the ▾ friend selector on its right - -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: - -The Library button in friend mode, purple, reading Sam's Library - -![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 | -|---|---| -| cassette button, not pressed | Not asked for. Click it to ask your friend for this. | -| cassette button, pressed | Asked for — this song is on its way to you. Click again to change your mind. | -| 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 | -|---|---| -| grey outline UFO | Not following. Click the UFO to follow this playlist. | -| 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 - : **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, - 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. +- Share playlists with friends! More info at [cassette.md](cassette.md) + -\ # BUT WAIT, THERE'S MORE diff --git a/cassette.md b/cassette.md new file mode 100644 index 0000000..f06d098 --- /dev/null +++ b/cassette.md @@ -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 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: + +The Library button with the ▾ friend selector on its right + +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: + +The Library button in friend mode, purple, reading Sam's Library + +![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 | +|---|---| +| cassette button, not pressed | Not asked for. Click it to ask your friend for this. | +| cassette button, pressed | Asked for — this song is on its way to you. Click again to change your mind. | +| 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 | +|---|---| +| grey outline UFO | Not following. Click the UFO to follow this playlist. | +| 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 + : **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. + diff --git a/extra-docs.md b/extra-docs.md index b7fd262..96457ef 100644 --- a/extra-docs.md +++ b/extra-docs.md @@ -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