7.1. Howdy Music Command Line Utilities

This section describes the four Howdy music command line utilities.

7.1.1. howdy_music_album

The help output, when running howdy_music_album -h, produces the following.

usage: howdy_music_album [-h] -a ARTIST_NAME [-A ALBUM_NAME] [--songs]
                           [--formatted] [--albums] [--debug] [--noverify]
                           [--musicbrainz]

optional arguments:
  -h, --help            show this help message and exit
  -a ARTIST_NAME, --artist ARTIST_NAME
                        Name of the artist to get album image for.
  -A ALBUM_NAME, --album ALBUM_NAME
                        Name of the album to get album image for.
  --songs               If chosen, get the song listing instead of downloading
                        the album image.
  --formatted           If chosen, print the song listing in a format
                        recognized by howdy_music_metafill for downloading a
                        collection of songs.
  --albums              If chosen, then get a list of all the songs in all
                        studio albums for the artist.
  --debug               Run with debug mode turned on.
  --noverify            If chosen, do not verify SSL connections.
  --musicbrainz         If chosen, use Musicbrainz to get the artist metadata.
                        Note that this is expensive, and is always applied
                        when the --albums flag is set.

These are the common operational flags,

  • --debug prints out DEBUG level logging output.
  • --noverify does not verify SSL connections.
  • By default, this executable uses the LastFM API to get music metadata. The --musicbrainz flag then means the MusicBrainz API is used.

Here are the three operations,

  • Download an album’s image to a PNG file in the current working directory. Here, the -a or --artist (artist) and -A or --album (album) need to be specified. To download the album image for the Moon Safari album released by Air,

    tanim-desktop $ howdy_music_album -a Air -A "Moon Safari"
    tanim-desktop $ Air.Moon Safari.png
    

    Here is the image,

    ../../_images/Air.Moon_Safari.png
  • The --albums flag gets a formatted, pretty-printed list of albums released by an artist. Here, the -a or --artist (artist) need to be specified. For example, for Air,

    tanim-desktop $ howdy_music_albums -a Air --albums
    
    Air has 7 studio albums.
    
    Studio Album                         Year    # Tracks
    ---------------------------------  ------  ----------
    Moon Safari                          1998          10
    10 000 Hz Legend                     2001          12
    City Reading (Tre Storie Western)    2003          19
    Talkie Walkie                        2004          11
    Pocket Symphony                      2006          12
    Love 2                               2009          12
    Music for Museum                     2014           9
    
  • The --song flag returns a list of songs released on a specific album by the artist. Here, the -a or --artist (artist) and -A or --album (album) need to be specified.

    • By default, the standard pretty-printed formatting if we do not use the --formatted flag. To get all the songs in track order for Moon Safari album released by Air,

      tanim-desktop $ howdy_music_album -a Air -A "Moon Safari" --songs
      
      Song                                        Track #
      ----------------------------------------  ---------
      La Femme d'Argent                                 1
      Sexy Boy                                          2
      All I Need                                        3
      Kelly Watch the Stars                             4
      Talisman                                          5
      Remember                                          6
      You Make It Easy                                  7
      Ce Matin-Là                                       8
      New Star in the Sky (Chanson Pour Solal)          9
      Le Voyage De Pénélope                            10
      
    • If we run with the --formatted flag, then the output is a semi-colon-delimited collection of songs in this album. This is an input format that can then be processed by howdy_music_metafill. For songs in the Moon Safari album released by Air,

      tanim-desktop $ howdy_music_album -a Air -A "Moon Safari" --songs --formatted
      
      La Femme d'Argent;Sexy Boy;All I Need;Kelly Watch the Stars;Talisman;Remember;You Make It Easy;Ce Matin-Là;New Star in the Sky (Chanson Pour Solal);Le Voyage De Pénélope
      

7.1.2. howdy_music_metafill

The help output, when running howdy_music_metafill -h, produces the following.

usage: howdy_music_metafill [-h] -s SONG_NAMES -a ARTIST_NAME
                              [--maxnum MAXNUM] [-A ALBUM_NAME] [--noverify]

optional arguments:
  -h, --help            show this help message and exit
  -s SONG_NAMES, --songs SONG_NAMES
                        Names of the song to put into M4A files. Separated by
                        ;
  -a ARTIST_NAME, --artist ARTIST_NAME
                        Name of the artist to put into the M4A file.
  --maxnum MAXNUM       Number of YouTube video choices to choose for your
                        song. Default is 10.
  -A ALBUM_NAME, --album ALBUM_NAME
                        If defined, then use ALBUM information to get all the
                        songs in order from the album.
  --noverify            If chosen, do not verify SSL connections.

Here are the common elements of its operation,

  • the --noverify flag means to not verify SSL connections.
  • the --maxnum setting is the maximum numbr of YouTube clips from which to choose. This must be \(\ge 1\), and its default is 10.
  • the artist must always be specified with the -a or --artist setting.

This executable has two modes of operation. In each mode, for each song in the collection, this tool finds that song, finds that clip, and asks the user to select a clip with a number from 1 to at most maxnum. For convenience, each YouTube clip also shows its duration in MM:SS format. For example, here I choose YouTube clip #1 for the first track in the Moon Safari album released by Air,

ACTUAL ARTIST: Air
ACTUAL ALBUM: Moon Safari
ACTUAL YEAR: 1998
ACTUAL NUM TRACKS: 10
ACTUAL SONG: La Femme d'Argent
Choose YouTube video:
1: Air - La Femme d'Argent (07:12)
2: Air - La Femme D'Argent (07:11)
3: Air - La Femme D'Argent (05:55)
4: La Femme D'Argent Extended - 26 Seamless Minutes (26:37)
5: La femme d'argent (07:07)
6: Air - La Femme d'Argent (Live at Canal+ 17.06.2016) HD (08:39)
7: AIR - La Femme D'Argent (Live in France, 2007) (10:13)
8: Air - La Femme D'Argent (EXTENDED 1H47) (01:47:42)
9: Air - La femme d'argent 432hz (07:11)
10: San Francisco 1906 with music by Air - La Femme D'Argent (07:06)
1
[youtube] U4U19zwFENs: Downloading webpage
[youtube] U4U19zwFENs: Downloading video info webpage
WARNING: Unable to extract video title
[download] Air.La Femme d'Argent.m4a has already been downloaded
[download] 100% of 6.90MiB
[ffmpeg] Correcting container in "Air.La Femme d'Argent.m4a"
  • In the first mode of operation, give it a list of songs separated by semicolons. The format of songs is described in this bullet point, e.g.,

    La Femme d'Argent;Sexy Boy;All I Need;Kelly Watch the Stars;Talisman;Remember;You Make It Easy;Ce Matin-Là;New Star in the Sky (Chanson Pour Solal);Le Voyage De Pénélope
    

    For songs in order in the album Moon Safari by Air. Below is an animation showing how this works in practice when downloading these songs. Here we always choose YouTube clip #1.

    The list of songs came from the LastFM service, and Gracenote cannot find Air songs in Moon Safari with the names Ce Matin-Là and Le Voyage De Pénélope due (probably) to diacritical accents.

  • In the second mode of operation, give it the album name with -A or --album. For example howdy_music_metafill -a Air -A "Moon Safari" to get all ten songs in this album,

    Here Gracenote is able to find all songs, including Ce Matin La (instead of Ce Matin-Là) and Le Voyage De Penelope (instead of Le Voyage De Pénélope).

7.1.3. howdy_music_songs

The help output, when running howdy_music_songs -h, produces the following.

usage: howdy_music_songs [-h] -a ARTIST_NAME -s SONG_NAMES [--maxnum MAXNUM]
                           [-A ALBUM_NAME] [--new] [--artists ARTIST_NAMES]
                           [--lastfm] [--musicbrainz] [--noverify] [--debug]

optional arguments:
  -h, --help            show this help message and exit
  -a ARTIST_NAME, --artist ARTIST_NAME
                        Name of the artist to put into the M4A file.
  -s SONG_NAMES, --songs SONG_NAMES
                        Names of the song to put into M4A files. Separated by
                        ;
  --maxnum MAXNUM       Number of YouTube video choices to choose for each of
                        your songs.Default is 10.
  -A ALBUM_NAME, --album ALBUM_NAME
                        If defined, then get all the songs in order from the
                        album.
  --new                 If chosen, use the new format for getting the song
                        list. Instead of -a or --artist, will look for
                        --artists. Each artist is separated by a ';'.
  --artists ARTIST_NAMES
                        List of artists. Each artist is separated by a ';'.
  --lastfm              If chosen, then only use the LastFM API to get song
                        metadata.
  --musicbrainz         If chosen, use Musicbrainz to get the artist metadata.
                        Note that this is expensive.
  --noverify            Do not verify SSL transactions if chosen.
  --debug               Run with debug mode turned on.

In all three operations, here are required arguments or common flags,

  • -a or --artist: the artist must always be specified.
  • --maxnum specifies the maximum number of YouTube video clips from which to choose. This number must be \(\ge 1\), and its default is 10.
  • --noverify does not verify SSL connections.
  • --debug prints out DEBUG level logging output.

Some example animated GIFs can be downloaded from here, and is mirrored in this project’s README:

howdy_music_cli_clip1 howdy_music_cli_clip2 howdy_music_cli_clip3
Download artists & songs Download artist & album Download sep artists & songs

The complicated collection of flags and arguments allows howdy_music_songs to download a collection of songs in three ways,

and using three music metadata services: Gracenote, LastFM, and MusicBrainz. The Gracenote service is used or started with by default, but,

  • --lastfm says to use or start with the LastFM API.
  • --musicbrainz says to use or start with the MusicBrainz API.
  • At most only one of --lastfm or --musicbrainz can be specified.

Each of the three operations can be either progressive or exclusive.

  • progressive means that the selection and downloading of songs starts with a given music service. If that service does not work, then it continues by order until successful. For example, if the Gracenote service does not work, then try LastFM; if LastFM does not work, then try MusicBrainz; if MusicBrainz does not work, then give up. Table 7.1 summarizes how this process works, based on the metadata choice flag (--lastfm, --musicbrainz, or none). The number in each cell determines the order in which to try until success – 1 means 1st, 2 means 2nd, etc.

    metadata flag
    gracenote_image_big
    lastfm_image_big
    musicbrainz_image_big
    default (no flag) 1 2 3
    --lastfm   1 2
    --musicbrainz     1
  • exclusive means that the selection of downloading of songs only uses a single given music service; if the songs cannot be found using it, then it gives up. Table 7.2 summarizes how this process works, matching metadata flag to music service.

    metadata flag
    gracenote_image_big
    lastfm_image_big
    musicbrainz_image_big
    default (no flag) 1    
    --lastfm   1  
    --musicbrainz     1

Once the metadata service finds the metadata for those songs, the CLI provides a selection of YouTube clips corresponding to a given song AND what the music metadata service thinks is the best match to the selected song. Each clip also shows the length (in MM:SS format) to let you choose one that is high ranking and whose length best matches the song’s length.

Here howdy_music_songs looks for a song, Remember by Air, using the music service MusicBrainz,

  1. The service finds the match and prints out the artist, album, and song.

    ACTUAL ARTIST: Air
    ACTUAL ALBUM: Moon Safari
    ACTUAL SONG: Remember (02:34)
    

    MusicBrainz always gives the song length after the song name (ACTUAL SONG row). LastFM may do so if it can find the song’s length (by internally using the MusicBrainz API). Gracenote does not have the song length information.

  2. A selection of candidate YouTube clips are given, each with duration. I find it best to choose a clip that is as highly ranked as possible and whose duration matches the actual song’s duration (if provided).

    ACTUAL ARTIST: Air
    ACTUAL ALBUM: Moon Safari
    ACTUAL SONG: Remember (02:34)
    Choose YouTube video:
    1: Air - Remember (04:13)
    2: Remember (02:35)
    3: Air - Remember (02:49)
    4: Remember (David Whitaker Version) (02:22)
    5: Air - Remember – Live in San Francisco (03:04)
    6: Air - Remember (03:41)
    7: Air - Remember – Outside Lands 2016, Live in San Francisco (02:40)
    8: Air - Remember (Original Mix) (03:14)
    9: AIR - Remember live@ FOX Oakland (02:38)
    10: Air - Remember (02:24)
    
  3. Make a selection from the command line, such as 2 (because the high ranking clip’s duration matches the song’s duration very closely). The song then downloads into the file, Air.Remember.m4a, in the current working directory.

    ACTUAL ARTIST: Air
    ACTUAL ALBUM: Moon Safari
    ACTUAL SONG: Remember (02:34)
    Choose YouTube video:
    1: Air - Remember (04:13)
    2: Remember (02:35)
    3: Air - Remember (02:49)
    4: Remember (David Whitaker Version) (02:22)
    5: Air - Remember – Live in San Francisco (03:04)
    6: Air - Remember (03:41)
    7: Air - Remember – Outside Lands 2016, Live in San Francisco (02:40)
    8: Air - Remember (Original Mix) (03:14)
    9: AIR - Remember live@ FOX Oakland (02:38)
    10: Air - Remember (02:24)
    2
    [youtube] JqMdhEy4hG8: Downloading webpage
    [youtube] JqMdhEy4hG8: Downloading video info webpage
    WARNING: Unable to extract video title
    [youtube] JqMdhEy4hG8: Downloading js player vflGnuoiU
    [youtube] JqMdhEy4hG8: Downloading js player vflGnuoiU
    [download] Destination: Air.Remember.m4a
    [download] 100% of 2.38MiB in 00:02
    [ffmpeg] Correcting container in "Air.Remember.m4a"
    

7.1.3.1. download songs using --songs and --artist flag

Here, one specifies the collection of songs to download by giving the artist and list of songs through --songs. Each song is separated by a “;”. The metadata service to use here is progressive. For example, to get Don’t be Light and Mer du Japon by Air using the MusicBrainz service,

We generate this video by running this command,

howdy_music_songs -a Air -A "Don't Be Light;Mer du Japon" --musicbrainz

7.1.3.2. download songs using --artist and --album flag

One specifies the collection of songs to download by giving the artist and album through --album. The metadata service to use is progressive. You can get the list of albums produced by the artist by running howdy_music_albums –artist=”artist” –albums. The clip below demonstrates how to get the album Moon Safari by Air using the MusicBrainz service,

We generate this video by running this command,

howdy_music_songs -a Air -A "Moon Safari" --musicbrainz

7.1.3.3. download songs using --new, --artists and --songs

Here, one uses the –new` flag and specifies, IN ORDER, the artists (using the --artists argument) and respective songs (using the --songs argument) to download the collection of songs. Artists are separated by “;” and songs are separated by “;”. The metadata service to use here is exclusive. For example, to get these two songs by two different artists using the MusicBrainz service,

We run this command,

howdy_music_songs --new --artists="Ximena Sariñana;Natalia Lafourcade" -s "Different;Piensa en Mí" --musicbrainz

whose video is shown below,

7.1.4. upload_to_gmusic

The help output, when running upload_to_gmusic -h, produces the following.

usage: upload_to_gmusic [-h] -f FILENAMES [-P] [--noverify]

optional arguments:
  -h, --help            show this help message and exit
  -f FILENAMES, --filenames FILENAMES
                        Give the list of filenames to put into the Google
                        Music Player.
  -P                    If chosen, then push Google Music API Mobileclient
                        credentials into the configuration database.
  --noverify            If chosen, do not verify SSL connections.

The --noverify flag disables verification of SSL HTTP connections. The standard operation of this tool is to upload songs to your Google Play Music account. The -f or --filenames argument can take semicolon-delimited filenames, or standard POSIX globs, for example,

upload_to_gmusic -f "Air.*m4a"

attempts to upload all filenames that match Air.*m4a.

The other mode of operation, running with the -P flag without specifying files to upload, attempts to refresh the gmusicapi Mobileclient OAuth2 credentials. Its operation is similar to that of howdy_store_credentials. These dialogs in the shell appear,

tanim-desktop $ upload_to_gmusic -P
Please go to this URL in a browser window:https://accounts.google.com/o/oauth2/auth...
After giving permission for Google services on your behalf,
type in the access code:

Second, go to the URL to which you are instructed. Once you copy that URL into your browser, you will follow a set of prompts asking you to choose which Google account to allow access, and to allow permissions for this app to access your Google Play Music account.

Third, paste the code similar to as described in Step #7 into the interactive text dialog, ...type in the access code:. Once successful, you will receive this message in the shell,

Success. Stored GMusicAPI Mobileclient credentials.