feat(scanner): Calibre-aligned OPF metadata extraction

Adopt Calibre's reading conventions for the Dublin Core metadata that parseOPFContent now pulls from the structured OPF parse: - Titles: EPUB3 title-type selection (prefer 'main', join a distinct subtitle with ': ' exactly as Calibre stores it). There is no separate subtitle column by design - Calibre-sidecar books arrive pre-joined, so a column would stay empty for most libraries and force every client to reimplement concatenation. - Genre: first dc:subject, mirroring the existing processGenresAndTags behavior of the Calibre-sidecar path; the embedded path never populated Genre before. Subjects stay one-element-one-tag - Library of Congress headings legitimately contain commas ("Holmes, Sherlock (Fictitious character) -- Fiction") and must not be split. - Identifiers: urn:isbn:/urn:asin: prefixed values parse in addition to opf:scheme attributes, and the scheme-less fallback now requires an ISBN-shaped value (10/13 digits, optional separators/trailing X) so URIs like the Gutenberg identifiers cannot masquerade as ISBNs - observed live on 'A Study in Scarlet'. - Series: EPUB3 belongs-to-collection with collection-type=series and group-position refines, ahead of the classic calibre:series metas. - Audiobookshelf metadata.json sidecars join their subtitle field into the title the same way. Tests cover title-type main+subtitle joining, belongs-to-collection series with fractional group-position, urn:isbn extraction, genre/tag parity, and comma preservation inside subject headings.
2026-09-12 23:45:18 -04:00
parent 72d167005f
commit 1fa8ee3a59
3 changed files with 255 additions and 65 deletions
@@ -1024,9 +1024,10 @@ func extractAudiobookshelfSidecar(path string) *MediaMetadata {
 	}

 	var sidecar struct {
-		Title   string   `json:"title"`
-		Authors []string `json:"authors"`
-		Series  []struct {
+		Title    string   `json:"title"`
+		Subtitle string   `json:"subtitle"`
+		Authors  []string `json:"authors"`
+		Series   []struct {
 			Series   string `json:"series"`
 			Sequence string `json:"sequence"`
 		} `json:"series"`
@@ -1048,6 +1049,11 @@ func extractAudiobookshelfSidecar(path string) *MediaMetadata {
 	metadata := &MediaMetadata{
 		Title: strings.TrimSpace(sidecar.Title),
 	}
+	// Subtitle joins the title Calibre-style ("Main: Subtitle") - there is no
+	// separate subtitle column, and Calibre-sidecar books arrive pre-joined.
+	if subtitle := strings.TrimSpace(sidecar.Subtitle); subtitle != "" && metadata.Title != "" {
+		metadata.Title = metadata.Title + ": " + subtitle
+	}
 	if len(sidecar.Authors) > 0 {
 		metadata.Author = strings.TrimSpace(sidecar.Authors[0])
 	}
@@ -1721,80 +1727,75 @@ func (s *MediaScanner) parseCalibreMetadataOPF(opfPath string) (*MediaMetadata,

 // parseOPFContent parses an OPF document (Dublin Core metadata) into
 // MediaMetadata. Used for both Calibre metadata.opf sidecars and the OPF
-// embedded inside an EPUB - the dc:* vocabulary is identical. Namespace-aware
-// parsing means it tolerates wherever the xmlns:dc declaration lives.
+// embedded inside an EPUB - the dc:* vocabulary is identical. Parsing is
+// attribute-order agnostic and namespace aware (see media_scanner_opf.go);
+// title selection and series detection follow Calibre's behavior.
 func parseOPFContent(content []byte) (*MediaMetadata, error) {
-	// Define XML structure for parsing with full Dublin Core namespace URLs
-	var opf struct {
-		XMLName  xml.Name `xml:"package"`
-		Metadata struct {
-			XMLName     xml.Name `xml:"metadata"`
-			Titles      []string `xml:"http://purl.org/dc/elements/1.1/ title"`
-			Creators    []string `xml:"http://purl.org/dc/elements/1.1/ creator"`
-			Subjects    []string `xml:"http://purl.org/dc/elements/1.1/ subject"`
-			Desc        []string `xml:"http://purl.org/dc/elements/1.1/ description"`
-			Publisher   []string `xml:"http://purl.org/dc/elements/1.1/ publisher"`
-			Dates       []string `xml:"http://purl.org/dc/elements/1.1/ date"`
-			Language    []string `xml:"http://purl.org/dc/elements/1.1/ language"`
-			Identifiers []struct {
-				Scheme string `xml:"http://www.idpf.org/2007/opf scheme,attr"`
-				Value  string `xml:",chardata"`
-			} `xml:"http://purl.org/dc/elements/1.1/ identifier"`
-			Contributors []string `xml:"http://purl.org/dc/elements/1.1/ contributor"`
-			// Calibre-specific meta tags - capture all, filter later
-			MetaTags []struct {
-				Name  string `xml:"name,attr"`
-				Value string `xml:"content,attr"`
-			} `xml:"meta"`
-		} `xml:"metadata"`
-	}
-	// Parse XML
-	if err := xml.NewDecoder(bytes.NewReader(content)).Decode(&opf); err != nil {
+	opf, err := parseOPFXML(content)
+	if err != nil {
 		return nil, fmt.Errorf("failed to parse OPF XML: %v", err)
 	}
+	md := opf.Metadata
+
 	// Map to MediaMetadata struct
 	metadata := &MediaMetadata{}
-	// Title (required)
-	if len(opf.Metadata.Titles) > 0 {
-		metadata.Title = opf.Metadata.Titles[0]
+	// Title: EPUB3 title-type main selection with Calibre-style subtitle join
+	if title := opf.selectTitle(); title != "" {
+		metadata.Title = title
 	}
 	// Author (first creator)
-	if len(opf.Metadata.Creators) > 0 {
-		metadata.Author = opf.Metadata.Creators[0]
+	if len(md.Creators) > 0 {
+		metadata.Author = md.Creators[0]
 	}
-	// Tags (all subjects)
-	if len(opf.Metadata.Subjects) > 0 {
-		metadata.Tags = utils.NormalizeTags(opf.Metadata.Subjects)
+	// Tags (all subjects; one element = one tag, commas are legal inside
+	// subject headings like "Holmes, Sherlock (Fictitious character)").
+	// Genre mirrors the sidecar path's processGenresAndTags: first subject.
+	if len(md.Subjects) > 0 {
+		metadata.Tags = utils.NormalizeTags(md.Subjects)
+		if len(metadata.Tags) > 0 {
+			metadata.Genre = metadata.Tags[0]
+		}
 	}
 	// Description
-	if len(opf.Metadata.Desc) > 0 {
-		metadata.Description = opf.Metadata.Desc[0]
+	if len(md.Descriptions) > 0 {
+		metadata.Description = md.Descriptions[0]
 	}
 	// Publisher
-	if len(opf.Metadata.Publisher) > 0 {
-		metadata.Publisher = opf.Metadata.Publisher[0]
+	if len(md.Publishers) > 0 {
+		metadata.Publisher = md.Publishers[0]
 	}
 	// Language
-	if len(opf.Metadata.Language) > 0 && opf.Metadata.Language[0] != "" {
-		metadata.Language = opf.Metadata.Language[0]
+	if len(md.Languages) > 0 && md.Languages[0] != "" {
+		metadata.Language = md.Languages[0]
 	}
 	// Publish date
-	if len(opf.Metadata.Dates) > 0 {
-		if date, err := time.Parse("2006-01-02T15:04:05Z07:00", opf.Metadata.Dates[0]); err == nil {
+	if len(md.Dates) > 0 {
+		if date, err := time.Parse("2006-01-02T15:04:05Z07:00", md.Dates[0]); err == nil {
 			metadata.PublishDate = date
-		} else if date, err := time.Parse("2006-01-02", opf.Metadata.Dates[0]); err == nil {
+		} else if date, err := time.Parse("2006-01-02", md.Dates[0]); err == nil {
 			metadata.PublishDate = date
 		} else {
 			// Try alternative date formats
-			if date, err := time.Parse("2006", opf.Metadata.Dates[0]); err == nil {
+			if date, err := time.Parse("2006", md.Dates[0]); err == nil {
 				metadata.PublishDate = date
 			}
 		}
 	}
-	// Identifiers (ISBN, ASIN)
-	for _, id := range opf.Metadata.Identifiers {
+	// Identifiers: opf:scheme attribute first, then URN-prefixed values
+	// (urn:isbn:...), then bare values that normalize to a valid ISBN.
+	for _, id := range md.Identifiers {
 		value := strings.TrimSpace(id.Value)
-		switch strings.ToUpper(id.Scheme) {
+		scheme := strings.ToUpper(strings.TrimSpace(id.Scheme))
+		if scheme == "" {
+			if lower := strings.ToLower(value); strings.HasPrefix(lower, "urn:") {
+				rest := value[4:]
+				if prefix, val, ok := strings.Cut(rest, ":"); ok {
+					scheme = strings.ToUpper(prefix)
+					value = strings.TrimSpace(val)
+				}
+			}
+		}
+		switch scheme {
 		case "ISBN":
 			metadata.ISBN = utils.NormalizeISBNSafe(value)
 		case "ASIN":
@@ -1803,28 +1804,30 @@ func parseOPFContent(content []byte) (*MediaMetadata, error) {
 			// Store UUID in hash info, not metadata
 			// Will be extracted by extractHashInfo()
 		default:
-			// EPUB3 identifiers often carry no opf:scheme attribute;
-			// accept a bare value that normalizes to a valid ISBN.
-			if metadata.ISBN == "" && id.Scheme == "" {
-				if normalized := utils.NormalizeISBNSafe(value); normalized != "" {
+			// EPUB3 identifiers often carry no opf:scheme attribute; accept a
+			// bare value only when it is ISBN-shaped (rejects the URIs and
+			// UUIDs that commonly share the identifier list).
+			if metadata.ISBN == "" && scheme == "" && isISBNLike(value) {
+				if normalized, err := utils.NormalizeISBN(value); err == nil {
 					metadata.ISBN = normalized
 				}
 			}
 		}
 	}
 	// Contributors
-	if len(opf.Metadata.Contributors) > 0 {
-		metadata.Contributors = utils.NormalizeContributors(opf.Metadata.Contributors)
+	if len(md.Contributors) > 0 {
+		metadata.Contributors = utils.NormalizeContributors(md.Contributors)
+	}
+	// Series: EPUB3 belongs-to-collection, then calibre:series metas
+	if series, index := opf.readSeries(); series != "" {
+		metadata.Series = series
+		if index > 0 {
+			metadata.SeriesNumber = int32(index)
+		}
 	}
 	// Calibre-specific meta tags (filter by name attribute)
-	for _, meta := range opf.Metadata.MetaTags {
+	for _, meta := range md.Metas {
 		switch meta.Name {
-		case "calibre:series":
-			metadata.Series = meta.Value
-		case "calibre:series_index":
-			if index, err := strconv.ParseFloat(meta.Value, 32); err == nil {
-				metadata.SeriesNumber = int32(index)
-			}
 		case "calibre:rating":
 			// Not imported (ratings are per-user in Bookhoard)
 		case "calibre:title_sort":