=== Vinilogy Covers ===
Contributors: vinilogy
Tags: woocommerce, album covers, vinyl, product images, music
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 0.2.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Finds the missing album covers of your WooCommerce record shop and sets them only after you approve them.

== Description ==

Many independent record shops have hundreds or thousands of records online without a cover, or with the same placeholder image on every product. Vinilogy Covers finds those products, looks each record up in the Vinilogy catalogue and downloads its cover from Cover Art Archive.

It needs a free Vinilogy key, which you request by email (see "Installation"), and it talks to the services listed under "External services".

Nothing changes in your shop until you say so:

* Covers are downloaded to your media library and wait for your review.
* Each proposal shows the album found, why it was matched and a confidence score.
* Approve them one by one, the ones you select, or all above a confidence level.
* Anything you approve can be undone; discarded downloads are deleted.

How records are identified, from most to least reliable:

1. **Barcode** (EAN/UPC), read from the usual barcode fields or from the SKU when it is a valid barcode: the cover of that very edition.
2. **Artist and title**, read from product attributes or from the product name. Shop habits such as "SURNAME, NAME", "(LP, 180g)", "– COLOURED VINYL" or used-condition notes in the name ("VG+") are cleaned up before searching.

Proposals with a confidence of 85 or more come pre-selected. In our test with 100 records from one shop, every pre-selected proposal was correct; always review the rest.

**Optional Discogs fallback.** When Cover Art Archive has no image, the plugin can also use the Discogs cover from the Vinilogy catalogue. It is off by default: Discogs images are uploaded by its users and its terms restrict reusing them on other sites, so each shop decides. Every downloaded image records its source.

Vinilogy is a free comparison site for vinyl records sold by independent shops in Spain: https://www.vinilogy.com

== External services ==

This plugin relies on external services to find and download covers. It only contacts them after a shop administrator clicks "Find products without a cover", and then for each product in the queue (in the background, or while the Covers screen is open).

**Vinilogy cover lookup** – https://api.vinilogy.com (run by Vinilogy, https://www.vinilogy.com)
Used to identify each record and get the address of its cover.
Sent for each product without a cover: its barcode if it has one, otherwise the artist and title read from the product, plus the shop's Vinilogy key. No data about customers, orders or users is sent.
Terms: https://www.vinilogy.com/condiciones#portadas – Privacy: https://www.vinilogy.com/privacidad#portadas

**Cover Art Archive** (run by the MetaBrainz Foundation and the Internet Archive) – https://coverartarchive.org
The cover image is downloaded from coverartarchive.org, which redirects to the Internet Archive (archive.org). The request carries the usual connection data (IP address of your server, user agent).
Terms: https://musicbrainz.org/doc/About/Data_License and https://archive.org/about/terms.php – Privacy: https://metabrainz.org/privacy and https://archive.org/about/terms.php

**Discogs** (only if the shop turns on the fallback) – https://www.discogs.com
The cover image is downloaded from i.discogs.com. The request carries the usual connection data.
Terms: https://support.discogs.com/hc/en-us/articles/360009334593-API-Terms-of-Use – Privacy: https://support.discogs.com/hc/en-us/articles/360009334513-Privacy-Policy

== Installation ==

1. Install and activate the plugin (WooCommerce must be active).
2. Request a free key by emailing hola@vinilogy.com.
3. Open WooCommerce → Album covers, expand "Settings" at the bottom of the screen and paste the key.
4. Click "Find products without a cover" and review the proposals.

== Frequently Asked Questions ==

= Will it change my products without asking? =

No. Covers are only downloaded to the media library; a product changes only when you approve its cover, and you can undo it.

= What counts as "without a cover"? =

Products with no image, and products whose image is shared by many products (5 or more by default, adjustable), which is what a placeholder looks like. Products that already have their own cover are never touched, and if you set one by hand while a proposal is waiting, the proposal is dropped.

= Does it cost anything? =

No. The key is free and the plugin is free. Record shops are who Vinilogy is for.

= Where do the covers go before I approve them? =

To your media library, attached to the product but not used as its image. If you discard a proposal, that file is deleted.

= What does the confidence number mean? =

How sure the match is, from 0 to 100. Hover over it to see why: a barcode match of the exact edition scores highest; a match by artist and title scores lower when several albums or artists share that name. Proposals at 85 or more come pre-selected.

= What if a cover is wrong? =

Discard it, or undo it after approving: the product goes back to the image it had. You can always set your own image in the product editor, as usual.

= Does it work with variable products? =

It sets the cover of the parent product, like any other product. Variations keep their own images.

= My SKUs are not barcodes. Does it still work? =

Yes: the record is then identified by artist and title. A SKU is only treated as a barcode when it is a valid EAN/UPC (8, 12, 13 or 14 digits with a correct check digit).

= The search does not advance when I close the page =

Covers are fetched in the background by WordPress scheduled tasks. If your host has them disabled (DISABLE_WP_CRON), keep the Album covers screen open until the search finishes, or run `wp vinicov procesar`.

= A product says "Not found". What now? =

Either Vinilogy does not have that record, or it has no cover image. Check that the product name has the artist and the title, or add a barcode, and use "Search again" at the bottom of the screen.

= Who owns the covers? =

Their labels and artists. Record shops use them to show the album they sell. Cover Art Archive collects them for that kind of use; check its terms and, if you turn on the Discogs fallback, Discogs' terms.

= What happens when I delete the plugin? =

Its settings, queue and pending downloads are removed. Covers you already approved stay on your products; each image keeps a note of where it came from (Cover Art Archive or Discogs) in its custom fields, so you can find and remove them later if you ever need to.

= Does it work from the command line? =

Yes, with WP-CLI: `wp vinicov buscar` (queue products without a cover), `wp vinicov procesar` (fetch covers), `wp vinicov ok --confianza=85` (approve all with that confidence or more), `wp vinicov estado` (counts by state).

= How do I report a security issue? =

Write to hola@vinilogy.com. Please do not open a public issue.

== Screenshots ==

1. Proposals waiting for review, with the album found, the image source and the confidence of each match.
2. Covers already set: any of them can be undone.
3. Settings: Vinilogy key, placeholder detection and the optional Discogs fallback (off by default).

== Changelog ==

= 0.2.2 =
* Spanish (es_ES) translation now ships with the plugin, so it shows in Spanish right after installing.

= 0.2.1 =
* Longer prefix on all internal names, as requested by the WordPress.org plugin review.
* Translations now come from translate.wordpress.org.
* Clearer wording: approve, discard, undo. Messages say what happened to the products.
* Never overwrites a cover you set by hand while a proposal was waiting; undo only restores if the image is still the approved one.
* Pauses for ten minutes when the Vinilogy service cannot be reached, instead of retrying every minute.
* A SKU only counts as a barcode when it is a valid EAN/UPC. Artist attributes with commas are no longer cut.
* Duplicating or deleting a product no longer leaves cover data or files behind.
* Each batch stops after 20 seconds and carries on in the next one.

= 0.2.0 =
* Translatable (English base).
* Discogs fallback, off by default.
* Clean uninstall.
* Declared compatible with WooCommerce order storage and block checkout.

= 0.1.0 =
* First version, tested with 100 records of a real shop.
