diff --git a/README.md b/README.md index aec4042..3d91f35 100644 --- a/README.md +++ b/README.md @@ -168,8 +168,8 @@ One tag releases pine and spruce together. Write the release notes for the two p Commit the notes and push them to `main`. Then use the release script. ```sh -${EDITOR:-vi} docs/releases/v0.8.0.md -./scripts/release.sh v0.8.0 +${EDITOR:-vi} docs/releases/v0.8.1.md +./scripts/release.sh v0.8.1 ``` When the script publishes the GitHub Release, the `Release` workflow builds the two programs for Linux, macOS, and Windows. It attaches one archive for each program and each system to the release. diff --git a/docs/releases/v0.8.1.md b/docs/releases/v0.8.1.md new file mode 100644 index 0000000..0c26229 --- /dev/null +++ b/docs/releases/v0.8.1.md @@ -0,0 +1,132 @@ +# pine and spruce v0.8.1 + +This release corrects nine faults in the progress sync of pine. The progress +sync sends the position and the listening time to the Audiobookshelf server. +spruce has no change. + +## Installation + +```sh +go install github.com/Thelost77/pine@v0.8.1 +go install github.com/Thelost77/pine/cmd/spruce@v0.8.1 +``` + +As an alternative, download an archive from the release page. See "Binaries". + +## Binaries + +The release has one archive for each program and each system. The name of an +archive is `_v0.8.1__`: + +| System | Architecture | File type | +|--------|--------------|-----------| +| `linux` | `amd64`, `arm64` | `.tar.gz` | +| `darwin` (macOS) | `amd64`, `arm64` | `.tar.gz` | +| `windows` | `amd64` | `.zip` | + +Each archive contains the program, the `LICENSE` file of pine, and a `licenses` +directory. That directory has the license texts of Go and of the modules that +the program links. + +- A binary needs libmpv. See "Requirements". +- On Windows, put `libmpv-2.dll` in the directory of the program. The archive + does not contain it. +- The binaries are not signed. +- A GitHub Actions workflow builds the binaries on Linux with `CGO_ENABLED=0`. + No binary of this release has run on a test machine. + +## pine + +### Reliability and Correctness + +Finished items: + +* **A stop removed the finished mark of the last finished item.** pine restores + the last session at each start. For a finished item, that session starts at + the position 0. A quit, or the play of a different item, then told the server + that the item is not finished. pine now sends no progress for a session with + no new position and no listening time, and it closes that session with no + position. +* **The end of a book could lose its finished mark.** At the end of a book, + pine sent the last position with the value "not finished". If the server + handled the close of the session first, it marked the book as finished. The + progress update then removed the mark, and the server stored the position 0. + A stop now sends the position with no finished value, and the server applies + its own rule. Only "mark as finished" and "mark as not finished" send the + value. + +Listening time: + +* **Each sync sent the total listening time of the session.** pine sends a + sync each 30 seconds, and the server adds the listening time of each sync. + For one hour of play, the server stored about 61 hours. A sync now sends + only the listening time that the server does not have. +* **The listening time was the change of the position.** At the speed 2.0, one + hour of play counted as two hours. The listening time is now the time of the + clock while the player plays. A pause adds nothing. +* **A quit with ctrl+c sent the last listening time two times.** pine sent the + close of the session and the progress update two times. pine now sends them + one time. + +Position: + +* **A paused session sent a sync each 30 seconds.** The server stored the old + position again. That could replace a newer position from a second device. + pine now sends a sync only if the position or the listening time has a + change of 1 second or more. +* **A quit with `q` could lose the last position and the listening time.** The + program could end before the two requests left. pine now sends the two + requests and waits for the server before it ends. + +Sessions: + +* **Each sync failed after the server lost the session.** Audiobookshelf has + no open session after a restart, or after 36 hours with no change of the + session. pine wrote a log line and continued. The server stored no listening + time for the rest of the playback, and it stored the position only at the + stop. pine now opens a new session for the item, and sends the position and + the listening time to it. +* **The close of a session could fail at the play of a different item.** pine + sent the close of the old session and the play request at the same time. The + server closes the old session at a play request, and it then refused the + close of pine. The listening time of that close was lost. pine now waits for + the close before it sends the play request. + +### Changes of Behavior + +* A quit waits until the server has the last position. If the server does not + answer, a quit can take up to 5 seconds. Before, a quit with `q` ended + immediately. +* The play of a different item waits for the close of the old session. If the + server does not answer, the wait ends after 10 seconds. +* The listening time that pine sends is lower than before, because the old + values were too high. This release does not correct the values that the + server has. +* A position tick that comes more than 5 seconds after the last tick adds no + listening time, for example after a suspend of the machine. One pause can + lose up to 1 second of listening time. + +## spruce + +spruce has no change in this release. The changed packages, `internal/abs` and +`internal/app`, are part of pine only. + +## Development + +* Each correction has a test that failed before the correction. The tests use + a fake Audiobookshelf server and the mock player of the app tests. +* No real Audiobookshelf server ran for these corrections, and no real + playback ran. The statements about Audiobookshelf are from the source of + version 2.37.1. +* No quit ran in a real terminal, and no playback ran at a speed other than + 1.0. +* The position that libmpv reports for a paused session is not measured. If it + is 1 second or more from the start position of the session, a stop sends + that position, with no finished value. + +## Requirements + +- Go 1.26.4 or newer, for an installation from source +- libmpv from [mpv](https://mpv.io/) 0.34 or later +- pine: an [Audiobookshelf](https://www.audiobookshelf.org/) server +- spruce: a [Jellyfin](https://jellyfin.org/) account with a music library diff --git a/docs/spruce/README.md b/docs/spruce/README.md index de1df9d..849bc00 100644 --- a/docs/spruce/README.md +++ b/docs/spruce/README.md @@ -191,7 +191,7 @@ Commit the notes and all release changes. Push them to `main`. Then use the release script: ```sh -./scripts/release.sh v0.8.0 +./scripts/release.sh v0.8.1 ``` The script verifies the repository, creates and pushes the exact annotated tag,