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`.