pymtheg 2.6.0
A Python script to share songs from Spotify/YouTube as a 15 second clip.
Requires Python: >=3.6.3,<4.0.0
Keywords: music,video,audio,cli,utility

# pymtheg

A Python script to share songs from Spotify/YouTube as a 15 second clip.
[Designed for use with Termux.](https://github.com/markjoshwel/pymtheg/blob/main/TERMUX.md)

See the [repository](https://github.com/markjoshwel/pymtheg) for more installation and
contribution instructions/information.

[![asciicast](https://asciinema.org/a/485075.svg)](https://asciinema.org/a/485075)

## Installation

pymtheg requires [Python 3.6.3](https://python.org/) or later,
and [ffmpeg](https://ffmpeg.org/).

## Usage

```text
usage: pymtheg [-h] [-cs CLIP_START] [-ce CLIP_END] [-i IMAGE] [-d DIR]
               [-o OUT] [-sm] [-smd SAVE_MUSIC_DIR] [-nt]
               [-tf TIMESTAMP_FORMAT] [-e EXT] [-sda SDARGS] [-ffa FFARGS]
               [-ud] [-y]
               queries [queries ...]

a python script to share songs from Spotify/YouTube as a 15 second clip

positional arguments:
  queries               song queries (see querying)

options:
  -h, --help            show this help message and exit

clip options:
  -cs CLIP_START, --clip-start CLIP_START
                        specify clip start (default 0)
  -ce CLIP_END, --clip-end CLIP_END
                        specify clip end (default +15)
  -i IMAGE, --image IMAGE
                        specify custom image

output options:
  -d DIR, --dir DIR     directory to output to, formattable (see formatting)
  -o OUT, --out OUT     output file name format, formattable (see formatting)
  -sm, --save-music     save downloaded music
  -smd SAVE_MUSIC_DIR, --save-music-dir SAVE_MUSIC_DIR
                        directory for downloaded music, defaults to -d/--dir
  -nt, --no-timestamp   switch to exclude timestamps from output clip paths
  -tf TIMESTAMP_FORMAT, --timestamp-format TIMESTAMP_FORMAT
                        timestamp format, formattable (see formatting)
  -e EXT, --ext EXT     file extension, defaults to "mp4"

tool options:
  -sda SDARGS, --sdargs SDARGS
                        args to pass to spotdl
  -ffa FFARGS, --ffargs FFARGS
                        args to pass to ffmpeg for clip creation

pymtheg options:
  -ud, --use-defaults   use --clip-start as clip start and --clip-length as clip end
  -y, --yes             say yes to every y/n prompt

querying:
  queries must be any one of the following:
    1. text
      "<query>"
      e.g. "thundercat - them changes"
    2. spotify track/album url
      "<url>"
      e.g. "https://open.spotify.com/track/..."
    3. youtube source + spotify metadata
      "<youtube url>|<spotify url>"
      e.g. "https://youtube.com/watch?v=...|https://open.spotify.com/track/..."
    4. a path
      "<path>"
      e.g. "06 VERTIGO.flac"

argument defaults:
  -f, --ffargs:
    "-hide_banner -loglevel error -c:a aac -c:v libx264 -pix_fmt yuv420p -tune stillimage -vf scale='iw+mod(iw,2):ih+mod(ih,2):flags=neighbor'"
  -o, --out:
    "{artists} - {title}"
  -t, --timestamp-format:
    " ({cs}{cer})"

formatting:
  available placeholders:
    from spotdl:
      {artist}, {artists}, {title}, {album}, {playlist}
    from pymtheg:
      {cs}
        clip end as per [(h*)mm]ss
        e.g. 10648 (1h, 06m, 48s)
      {css}
        clip end in seconds
        e.g. 4008 (1h, 6m, 48s -> 4008s)
      {ce}
        clip end as per [(h*)mm]ss, e.g. 10703 (1h, 07m, 03s)
      {ces}
        clip end in seconds
        e.g. 4023 (1h, 07m, 03s -> 4023s)
      {cer}
        clip end relative to clip start, prefixed with +
        e.g. +15
    
      notes:
        1. pymtheg placeholders can only be used with `-tf, --timestamp-format`
        2. "[(h*)mm]ss": seconds and minutes will always be represented as 2
           digits and will be right adjusted with 0s if needed, unless they are
           the first shown unit where they _may_ have up to two characters.
           hours can be represented by any number of characters.
           e.g. "138:02:09", "1:59:08", "2:05", "6"

examples:
  1. get a song through a spotify link
    pymtheg "https://open.spotify.com/track/..."
  2. get a song through a search query
    pymtheg "thundercat - them changes"
  3. get multiple songs through multiple queries
    pymtheg "https://open.spotify.com/track/..." "<query 2>"
  4. get a random 15s clip of a song
    pymtheg "<query>" -cs "*" -ce "+15" -ud 

  note: see querying for more information on queries
```

## License

pymtheg is unlicensed with The Unlicense. In short, do whatever. You can find copies of
the license in the
[UNLICENSE](https://github.com/markjoshwel/pymtheg/blob/main/UNLICENSE) file or in the
[pymtheg module docstring](https://github.com/markjoshwel/pymtheg/blob/main/pymtheg.py#L5).