diff --git a/README.md b/README.md index 7e22e04..f9e9f0d 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,75 @@ # abs-tract -This is an "all-in-one" book metadata provider for AudioBookShelf that can currently pull metadata from Goodreads and Kindle Store. +This is an "all-in-one" book metadata provider for AudiobookShelf that can currently pull metadata from Goodreads and Kindle Store. -Current metadata providers plan to be improved and other metadata providers are on the roadmap. +Current metadata providers plan to be improved, and other metadata providers are on the roadmap. Please open issues for feature requests or new provider suggestions! + #### Why the name abs-tract? -I'm glad you asked - It's a fun play on words. AudioBookShelf is often abbreviated to ABS. Books can have abstracts. Plus we are abstracting away the providing of metadata from AudioBookShelf. Therefore abs-tract seemed suitably punny 💩 +I'm glad you asked - It's a fun play on words. AudiobookShelf is often abbreviated to ABS. Books can have abstracts. Plus, we are abstracting away the provision of metadata from AudiobookShelf. Therefore, abs-tract seemed suitably punny 💩 + ## Providers ### Goodreads #### Pros: + - A very good provider of general metadata for books. + #### Cons: + - Covers are quite low quality and often missing completely (see FAQ for reasoning) -- Goodreads has poor search functionality making finding a matching book sometimes very difficult. Your mileage may vary. 90% of my library is able to be matched. See FAQ for tips on finding a match +- Goodreads has poor search functionality, making finding a matching book sometimes very difficult. Your mileage may vary. 90% of my library is able to be matched. See FAQ for tips on finding a match + #### Metadata Provided: + - Title - Author - Cover - Low quality. **Sometimes missing** (see FAQ) - Original Publish Year - Series Name - Series Position -- Description - of "best" edition chosen by goodreads -- Genres - Top 3 chosen by goodreads users -- ISBN - of "best" edition chosen by goodreads. **Sometimes missing** -- Publisher - of "best" edition chosen by Goodreadns -- Language - of "best" edition chosen by Goodreadns +- Description - of "best" edition chosen by Goodreads +- Genres - Top 3 chosen by Goodreads users +- ISBN - of "best" edition chosen by Goodreads. **Sometimes missing** +- Publisher - of "best" edition chosen by Goodreads +- Language - of "best" edition chosen by Goodreads ### Kindle #### Pros: + - Provides extremely high quality covers. Will make your eyes cry with happiness. + #### Cons: -- Currently not much metadata is provided + +- Currently, not much metadata is provided + #### Metadata Provided: + - Title - Author - Cover - Crazy high quality - Publish Year - of edition chosen by Amazon. **Not original publish year** - ASIN + ## Running -The best way to run abs-goodreads is to use docker. +The best way to run abs-tract is to use Docker. To run abs-tract using Docker, use the following command: ```bash docker run -d \ - --name abs-goodreads \ + --name abs-tract \ -p 5555:5555 \ --restart unless-stopped \ - arranhs/abs-goodreads:latest + arranhs/abs-tract:latest ``` ## Test -Test abs-goodreads is working using curl. +Test if abs-tract is working using curl. ### Goodreads @@ -65,6 +78,7 @@ ADDRESS=localhost curl --request GET \ --url "http://$ADDRESS:5555/goodreads/search?query=The+Hobbit&author=J.R.R.+Tolkien" ``` + ### Kindle ```bash @@ -72,56 +86,55 @@ ADDRESS=localhost curl --request GET \ --url "http://$ADDRESS:5555/kindle/uk/search?query=The+Hobbit&author=J.R.R.+Tolkien" ``` -## Setup with AudioBookShelf -You can then set up abs-goodreads in AudioBookShelf. +## Setup with AudiobookShelf + +You can then set up abs-tract in AudiobookShelf. ``` Settings -> Item Metadata Utils -> Custom Metadata Providers -> Add ``` -and entering the following details: +and enter the following details: ### Goodreads - Name: **GoodReads** -- URL: **http://\:5555/goodreads** -- Authorization Header Value: **\** +- URL: **http://:5555/goodreads** +- Authorization Header Value: **** ### Kindle - Name: **Kindle** -- URL: **http://\:5555/kindle/\** -- Authorization Header Value: **\ +- URL: **http://:5555/kindle/** +- Authorization Header Value: **** Region can be one of the following: -- au - Australia -- ca - Canada -- de - Germany +- au - Australia +- ca - Canada +- de - Germany - es - Spain -- fr - Franch -- in - Indian -- it - Italy +- fr - France +- in - India +- it - Italy - jp - Japan -- uk - United Kingdom +- uk - United Kingdom - us - United States ### Setup video walkthrough: -https://github.com/ahobsonsayers/abs-goodreads/assets/32173585/54437af6-a17c-4458-bb82-479b183171da +https://github.com/ahobsonsayers/abs-tract/assets/32173585/54437af6-a17c-4458-bb82-479b183171da ## FAQ -### Why is Goodreads not returning some covers? - -The Goodreads API will sometimes not return cover images due to a variety of factors, usually related to copyright and the requirement to honour terms and conditions. Unfortunately, this is not something we can fix while using the Goodreads API - covers will need to be sourced from elsewhere. +### Why is Goodreads not returning covers? -See the FAQ below for a possible future alternative way to retrieve Goodreads metadata, which could solve this issue. +The Goodreads API sometimes does not return cover images due to a variety of factors, usually related to copyright and the requirement to honor terms and conditions. Unfortunately, this is not something we can fix while using the Goodreads API - covers will need to be sourced from elsewhere. ### How are you using the Goodreads API? Hasn't it been shut down? -Yes, since 8th December 2020, Goodreads no longer issues new API keys and plans to retire their API entirely in the future. +Yes, since 8th, December 2020, Goodreads no longer issues new API keys and plans to retire their API entirely in the future. However, thanks to [LazyLibrarian](https://gitlab.com/LazyLibrarian/LazyLibrarian), we can use the read-only key they provide until Goodreads shuts down the API for good.