github.com/derat/nup@v0.0.0-20230418113745-15592ba7c620/cmd/nup/README.md (about) 1 # `nup` executable 2 3 This directory contains a `nup` command-line program that interacts with the 4 [App Engine server]. The program supports various subcommands that are 5 described below. 6 7 [App Engine server]: ../../server 8 9 ``` 10 Usage: nup <flags> <subcommand> <subcommand args> 11 12 Subcommands: 13 check check for issues in songs and cover images 14 commands list all command names 15 config manage server configuration 16 covers manage album art 17 debug print information about a song file 18 dump dump songs from the server 19 flags describe all known top-level flags 20 help describe subcommands and their syntax 21 metadata update song metadata 22 projectid print GCP project ID 23 query run song queries against the server 24 storage update song storage classes 25 update send song updates to the server 26 27 -config string 28 Path to config file (default "~/.nup/config.json") 29 ``` 30 31 ## `check` command 32 33 The `check` command checks for issues in JSON-marshaled [Song] objects dumped by 34 the `dump` command or in cover images. 35 36 [Song]: ../../server/db/song.go 37 38 ``` 39 check <flags>: 40 Check for issues in dumped songs read from stdin. 41 42 -checks string 43 Comma-separated list of checks to perform: 44 album-id Songs have MusicBrainz album IDs 45 cover-size-400 Cover images are at least 400x400 46 cover-size-800 Cover images are at least 800x800 47 imported Local songs have been imported 48 metadata Song metadata is the same in dumped and local songs 49 song-cover Songs with album IDs have cover files 50 unused-cover Cover image files are referenced by songs 51 (default "album-id,imported,song-cover,unused-cover") 52 ``` 53 54 ## `config` command 55 56 The `config` command prints or updates the server's saved configuration in 57 [Datastore]. See the [Config](../../server/config/config.go) struct for details. 58 59 ``` 60 config [flags]: 61 Manage the App Engine server's configuration in Datastore. 62 By default, prints the existing JSON-marshaled configuration. 63 64 -delete-instances 65 Delete running instances after setting config 66 -service string 67 Service name for -delete-instances (default "default") 68 -set string 69 Path of updated JSON config file to save to Datastore 70 ``` 71 72 [Datastore]: https://cloud.google.com/datastore 73 74 ## `covers` command 75 76 The `covers` command manipulates local cover images. 77 78 With the `-download` flag, it reads JSON-marshaled [Song] objects written by the 79 `dump` command and downloads the corresponding album artwork from the [Cover Art 80 Archive]. 81 82 Google Images is also convenient for finding album artwork. A custom search for 83 high-resolution square images can be added to Chrome by going to 84 `chrome://settings/searchEngines?search=search+engines` and entering the 85 following information: 86 87 * Search engine: `Google Image Search Album Art` 88 * Keyword: `album` 89 * URL: `https://www.google.com/search?as_st=y&tbm=isch&hl=en&as_q=%s&as_epq=&as_oq=&as_eq=&cr=&as_sitesearch=&safe=images&tbs=isz:l,iar:s` 90 91 [Cover Art Archive]: https://coverartarchive.org/ 92 93 With the `-generate-webp` flag, it generates smaller [WebP] versions at various 94 sizes of all of the JPEG images in `-cover-dir`. The server's `/cover` endpoint 95 returns a WebP image if available when passed the `webp=1` parameter. WebP 96 images should be generated before syncing the local cover directory to Cloud 97 Storage. 98 99 [WebP]: https://developers.google.com/speed/webp 100 101 ``` 102 covers <flags>: 103 Manipulate album art images in a directory. 104 With -download, downloads album art from coverartarchive.org. 105 With -generate-webp, generates WebP versions of existing JPEG images. 106 107 -cover-dir string 108 Directory containing cover images 109 -download 110 Download covers for dumped songs read from stdin or positional song files to -cover-dir 111 -download-size int 112 Image size to download (250, 500, or 1200) (default 1200) 113 -generate-webp 114 Generate WebP versions of covers in -cover-dir 115 -max-downloads int 116 Maximum number of songs to inspect for -download (default -1) 117 -max-requests int 118 Maximum number of parallel HTTP requests for -download (default 2) 119 ``` 120 121 ## `debug` command 122 123 The `debug` command prints information about a song file specified in the 124 command line. 125 126 ``` 127 debug <flags> <path>...: 128 Print information about one or more song files. 129 130 -id3 131 Print all ID3v2 text frames 132 -mpeg 133 Read MPEG frames and print size/duration info 134 ``` 135 136 ## `dump` command 137 138 The `dump` command downloads all song metadata and user data from the [App 139 Engine server] and writes JSON-marshaled [Song] objects to stdout. 140 141 ``` 142 dump <flags>: 143 Dump JSON-marshaled song data from the server to stdout. 144 145 -play-batch-size int 146 Size for each batch of entities (default 800) 147 -song-batch-size int 148 Size for each batch of entities (default 400) 149 ``` 150 151 ## `metadata` command 152 153 The `metadata` command queries [MusicBrainz] for updated song metadata. 154 155 ``` 156 metadata <flags> <path>...: 157 Fetch updated metadata from MusicBrainz and write override files. 158 -scan updates the specified songs or all songs (without positional arguments). 159 -set-album changes the album of songs in specified dir(s). 160 -set-non-album updates the specified song file(s) to be non-album tracks. 161 -print prints current on-disk metadata for the specified file(s). 162 -print-full additionally includes SHA1s and lengths. 163 164 -dry-run 165 Don't write override files 166 -log-updates 167 Log updates to stdout (default true) 168 -print 169 Print metadata from specified song file(s) 170 -print-full 171 Like -print, but include SHA1 and length (slower) 172 -scan 173 Scan songs for updated metadata 174 -set-album string 175 Update MusicBrainz release ID for songs in specified dir(s) 176 -set-non-album 177 Update specified file(s) to be non-album tracks 178 ``` 179 180 ## `projectid` command 181 182 The `projectid` command prints the GCP [project ID]. 183 184 [project ID]: https://cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin 185 186 ``` 187 projectid: 188 Print the Google Cloud Platform project ID (as derived from the 189 config's serverURL field). 190 ``` 191 192 ## `query` command 193 194 The `query` command performs a query using the server and writes the resulting 195 JSON-marshaled [Song] objects to stdout. 196 197 ``` 198 query <flags>: 199 Query the server and and print JSON-marshaled songs to stdout. 200 201 -filename string 202 Song filename (relative to music dir) to query for 203 -path string 204 Song path (resolved to music dir) to query for 205 -pretty 206 Pretty-print JSON objects 207 -print-id 208 Print song IDs instead of full JSON objects 209 -single 210 Require exactly one song to be matched 211 ``` 212 213 [MusicBrainz]: https://musicbrainz.org/ 214 215 ## `storage` command 216 217 The `storage` command reads JSON-marshaled [Song] objects written by the `dump` 218 command and updates each song file's [storage class] in [Google Cloud Storage] 219 based on its rating. 220 221 Check the current [Cloud Storage pricing], but for single-user use, it's 222 probably most economical to just set the song bucket's default storage class to 223 Coldline and use that for all songs. 224 225 [Google Cloud Storage]: https://cloud.google.com/storage 226 [storage class]: https://cloud.google.com/storage/docs/storage-classes 227 [Cloud Storage pricing]: https://cloud.google.com/storage/pricing 228 229 ``` 230 storage <flags>: 231 Update song files' storage classes in Google Cloud Storage based on 232 ratings in dumped songs read from stdin. 233 234 -bucket string 235 Google Cloud Storage bucket containing songs 236 -class string 237 Storage class for infrequently-accessed files (default "COLDLINE") 238 -max-updates int 239 Maximum number of files to update (default -1) 240 -rating-cutoff int 241 Minimum song rating for standard storage class (default 4) 242 -workers int 243 Maximum concurrent Google Cloud Storage updates (default 10) 244 ``` 245 246 ## `update` command 247 248 The `update` command updates the [App Engine server]'s song data. 249 250 By default, `update` scans the music directory from the config file and sends 251 metadata for all song files that have been added or modified since the previous 252 run. The `-force-glob` and `-song-paths-file` flags can be used to read specific 253 song files instead of scanning all files for changes. 254 255 The `-import-json-file` flag can be used to instead read JSON-marshaled [Song] 256 objects from a file. Note that any existing user data (ratings, tags, and 257 playback history) will be replaced by default, although this behavior can be 258 disabled by passing `-import-user-data=false`. 259 260 The `-delete-song` flag can be used to delete specific songs from the server 261 (e.g. after deleting them from the music dir). 262 263 ``` 264 update <flags>: 265 Send song updates to the server. 266 267 -compare-dump-file string 268 Path to JSON file with songs to compare updates against 269 -delete-after-merge 270 Delete source song if -merge-songs is true 271 -delete-song int 272 Delete song with given ID 273 -dry-run 274 Only print what would be updated 275 -dumped-gains-file string 276 Path to dump file from which songs' gains will be read (instead of being computed) 277 -force-glob string 278 Glob pattern relative to music dir for files to scan and update even if they haven't changed 279 -import-json-file string 280 Path to JSON file with songs to import 281 -import-user-data 282 When importing from JSON, replace user data (ratings, tags, plays, etc.) (default true) 283 -limit int 284 Limit the number of songs to update (for testing) 285 -merge-songs string 286 Merge one song's user data into another song, with IDs as "src:dst" 287 -print-cover-id string 288 Print cover ID for specified song file 289 -reindex-songs 290 Ask server to reindex all songs' search-related fields (not typically needed) 291 -require-covers 292 Die if cover images aren't found for any songs that have album IDs 293 -song-paths-file string 294 Path to file with one relative path per line for songs to force updating 295 -test-gain-info string 296 Hardcoded gain info as "track:album:amp" (for testing) 297 -use-filenames 298 Identify songs by filename rather than audio data hash (useful when modifying files) 299 ``` 300 301 ### Merging songs 302 303 Suppose you have an existing file `old/song.mp3` that's already been rated, 304 tagged, and played. You just added a new file `new/song.mp3` that contains a 305 better (e.g. higher-bitrate) version of the same song from a different album. 306 You want to delete the old file and merge its rating, tags, and play history 307 into the new file. 308 309 1. Run `nup update` to create a new database object for the new file. 310 2. Use `nup dump` to produce a local text file containing JSON representations 311 of all songs and find the old and new songs' `songId` properties in it. 312 Alternatively, find the songs' IDs using the "Debug" menu item in the web 313 interface, or run `nup query -print-id -single -path <PATH>`. 314 3. Run `nup update -merge-songs=<OLDID>:<NEWID> -delete-after-merge` to merge 315 the old song's user data into the new song and delete the old song from the 316 server. 317 4. Delete `old/song.mp3` or remove it from your local music directory. 318 319 Alternatively, you can just overwrite the old file with the new one and use `nup 320 update -use-filenames`.