diplodocus.org Git - flac-archive/blob - tags.pl

   1 package epg::flac::archive::tags;
   2
   3 =head1 NAME tags.pl
   4
   5 subroutines for tag processing
   6
   7 =head1 DESCRIPTION
   8
   9 TODO
  10
  11 =cut
  12
  13 # POSIX.1-2017, Base Definitions, 3.282  Portable Filename Character Set says
  14 #   [A-Za-z0-9._-]
  15 # https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282
  16
  17 # Flac tags (set with `flac -T fieldname=...`) are Vorbis comments.
  18 # https://www.xiph.org/vorbis/doc/v-comment.html#fieldnames field names we care about:
  19 # - TITLE - Track/Work name
  20 # - VERSION - may be used to differentiate multiple versions of the same track title in a single collection. (e.g. remix info)
  21 # - ALBUM - The collection name to which this track belongs
  22 # - TRACKNUMBER - The track number of this piece
  23 # - ARTIST - The artist generally considered responsible for the track
  24 # - DATE - Date the track was recorded (XXX I use US release date)
  25 # https://age.hobba.nl/audio/mirroredpages/ogg-tagging.html (supposedly mirrored from http://reactor-core.org/ogg-tagging.html )
  26 # specifies more:
  27 # - DISCNUMBER - if part of a multi-disc album, put the disc number here
  28 # - VERSION - e.g. "live", "radio edit"
  29 # - PARTNUMBER - part number if a work is divided across tracks
  30 # - PART - part name e.g. "Oh sole mio"
  31 # https://picard-docs.musicbrainz.org/en/appendices/tag_mapping.html
  32 # - ALBUMARTIST - maps to ID3v2 TPE2
  33
  34 # Input is a directory containing:
  35 # - trackNN.cdda.wav - WAV  format files ripped from CD-DA audio tracks where NN is track number 01 - 99
  36 # - tags - described below
  37 # - cover.front.jpeg - optional JPEG format file containing the album front cover
  38
  39 # The tags file is composed of two blocks:
  40 # 1. album tags
  41 # 2. track tags
  42 # Album tags may be:
  43 # - ALBUM
  44 # - ARTIST
  45 # - DATE
  46 # - DISCNUMBER (optional)
  47
  48 # Track tags may be any of the rest of the tags listed above, suffixed with
  49 # [N] where N is the track number.  ARTIST, and only ARTIST, may also appear
  50 # in the track tags.  In this case, it overrides the album artist.  In order
  51 # to add artists, the album artist must be listed again.  For example, Reba
  52 # McEntire's "The Heart Won't Lie" on the album "It's Your Call" features
  53 # Vince Gill, and is specified as:
  54 # ARTIST=Reba McEntire
  55 # ALBUM=It's Your Call
  56 # TITLE[5]=The Heart Won't Lie
  57 # ARTIST[5]=Reba McEntire
  58 # ARTIST[5]=Vince Gill
  59
  60 use v5.12;
  61 use warnings;
  62
  63 use Exporter 'import';
  64
  65 our @EXPORT_OK = qw[
  66     disc_tags
  67     read_tags
  68     mangle_for_file_name
  69     quote
  70     two_digits
  71 ];
  72
  73 sub two_digits {
  74     my $n = shift;
  75     my  $s = sprintf('%02d', $n);
  76     if (length($s) != 2) {
  77         die("$n won't fit into two digits")
  78     }
  79     $s
  80 }
  81
  82 sub read_tags {
  83     my $fh = shift;
  84     my %album;
  85     my @tracks;
  86     my $tracknum = 0;
  87     my $name;
  88     while (<$fh>) {
  89         chomp;
  90         if (!s/^([^=[\]]+)(\[(\d+)])?=//) {
  91             if (defined($name) && $name eq 'DESCRIPTION') {
  92                 # Qobuz offers FLAC files like this.
  93                 warn("looks like DESCRIPTION had multiple lines; discarding and returning early: $_");
  94                 last
  95             }
  96             die("no field name in:  $_");
  97         }
  98         $name = $1;
  99         # TODO validate $name
 100         # TODO album tags should be illegal after track tags
 101         if (defined($3)) {
 102             if ($3 == $tracknum + 2) {
 103                 $tracknum++;
 104             } elsif ($3 != $tracknum + 1) {
 105                 $tracknum++;    # increment from 0 to 1 for error message
 106                 die("illegal track number jump from $tracknum to $3")
 107             }
 108             push(@{$tracks[$tracknum]->{$name}}, $_);
 109         } else {
 110             push(@{$album{$name}}, $_);
 111         }
 112     }
 113
 114     \%album, \@tracks
 115 }
 116
 117 sub one_or_undef {
 118     my $name = shift;
 119     my $tags = shift;
 120     my $tag = $tags->{$name};
 121     if (defined($tag) && @$tag > 0) {
 122         return $tag->[0]
 123     }
 124     undef
 125 }
 126
 127 sub one {
 128     my $tag = one_or_undef(@_);
 129     if (!defined($tag)) {
 130         my $name = shift;
 131         die("exactly one $name tag required")
 132     }
 133     $tag
 134 }
 135
 136 =over
 137
 138 =item B<disc_tags>
 139
 140 Interpret the tags hash for a disc, returning:
 141
 142 =over
 143
 144 =item *
 145 Artist tag (exactly one required in the hash).
 146
 147 =item *
 148 Album tag (exactly one required).
 149
 150 =item *
 151 Date tag (zero or one required).
 152
 153 =item *
 154 Disc number (zero or one required) as a reference to an array of size 0 or 1.
 155
 156 =back
 157 =cut
 158 sub disc_tags {
 159     my %tags = @_;
 160
 161     if (!defined($tags{ALBUM}) || @{$tags{ALBUM}} != 1) {
 162         die('exactly one ALBUM tag required')
 163     }
 164     my $album_tag = $tags{ALBUM}->[0];
 165
 166     # TODO ALBUMARTIST
 167     if (!defined($tags{ARTIST}) || @{$tags{ARTIST}} != 1) {
 168         die('exactly one ARTIST tag required')
 169     }
 170     my $artist = $tags{ARTIST}->[0];
 171
 172     my $date;
 173     if (defined($tags{DATE})) {
 174         if (@{$tags{DATE}} != 1) {
 175             die('one or zero DATE tags required')
 176         }
 177         $date = $tags{DATE}->[0];
 178     }
 179
 180     my @discnumber = ();
 181     if (defined($tags{DISCNUMBER})) {
 182         if (@{$tags{DISCNUMBER}} != 1) {
 183             die('one or zero DISCNUMBER tags required')
 184         }
 185         my ($discnum) = @{$tags{DISCNUMBER}};
 186         @discnumber = ($discnum);
 187         # But check it against DISCTOTAL if present.
 188         my $total = $tags{DISCTOTAL};
 189         if (defined($total) && @$total > 0) {
 190             my ($total) = @$total;
 191             if ($total < $discnum) {
 192                 die("DISCNUMBER=$discnum > DISCTOTAL=$total")
 193             }
 194             if ($total == 1) {
 195                 # Qobuz offers FLAC files like this.
 196                 @discnumber = ();
 197             }
 198         }
 199     }
 200
 201     $artist, $album_tag, $date, \@discnumber
 202 }
 203
 204 sub mangle_for_file_name {
 205     my $fn = shift;
 206     $fn =~ s/[!,.?]//g;          # discard these punctuation marks
 207     $fn =~ s/\s+/_/g;            # replace all whitespace with _
 208     $fn =~ s/[^A-Za-z0-9_]/-/g;  # everything else with -
 209     $fn =~ s/_[_-]/_/g;          # collapse repeated _ or - to _
 210     $fn =~ s/-[_-]/_/g;          # more
 211     $fn =~ s/^[_-]+//;           # discard any _ or - at beginning
 212     $fn =~ s/[_-]+$//;           # at end too
 213     $fn
 214 }
 215
 216 sub quote {
 217     my $s = shift;
 218     $s =~ s/'/'\\''/g;
 219     "'$s'"
 220 }
 221
 222 =back
 223
 224 =cut
 225
 226 1;