Module documentation

Main player class

The main player providing most functionality you would need

class pYTerm.pYTerm.Player(songs=None, playlists=None, quiet: bool = False, shuffle: bool = False, volume: int = 100, muted: bool = False, rich_presence: bool = True, debuglogs: bool = False, legacystreams: bool = False, loop_queue: bool = False, backend: pYTerm.backends.AudioBackend = <pYTerm.backends.FFPyPlayerBackend object>, start_playing: bool = False)

Main player class

Parameters

  • songs (list, str) – one or more song titles/urls

  • playlists (list, str) – one or more urls to youtube playlists/paths to local playlist files

  • shuffle (bool) – whether or not to randomise the song queue

  • volume (int >= 0) – volume level (>100 gets distorted and LOUD)

  • rich_presence (bool) – whether or not to use discord rich presence to display the current song on discord

  • muted (bool) – whether or not to start the player muted

  • debuglogs (bool) – whether or not to print pYTerm debug logs

  • legacystreams (bool) – whether or not to use legacy streams, enable if some songs dont load

  • quiet (bool) – will not print anything if enabled

  • backend (AudioBackend) – audio backend instance to use. check the backends documentation

  • loop_queue (bool) – if True, will loop the song current queue back around to the start when the end is reached

  • start_playing (bool) – if True, will start playing the entire playlist immediatly, same as Player.play_all( halting=False, keep_alive = True )

add_local_playlist(file)

Adds songs from a local playlist file to the queue. playlist files are a list of youtube URLs or search words, with each entry on its own line

Parameters

file (str) – path to local playlist file

add_playlist(playlists)

Checks type of playlist and hands it off to the right function, which will then add it’s songs to the queue

Parameters

playlists (str, list) – one or more urls to youtube playlists or paths to local playlist files

add_song(songs)

Add one or multiple songs to the queue

Parameters

songs (list, str) – one or more songs or youtube urls to add to the queue

add_youtube_playlist(url)

Adds songs from a youtube playlist to the queue

Parameters

url (str) – url to youtube playlist

clear_songs()

empties the entire song queue

debug(*args)

Print debug-level log

get_current_time()

Returns a nicely formatted string of the current timestamp of the playing song

get_progress()

Returns a floating point number between 0.0 and 1.0 depending on how far along the player is in the song, where 0 is the start and 1 is the end.

get_song_index()

Returns the index of the currently playing song in the playlist

get_songs()

Returns the current playlist as a tuple

get_total_time()

Returns a nicely formatted string of the total duration of the current song

has_exited()

Returns True if the player has exited

increment_song_index(positive: bool = True, wrap: bool = True)

increments or decrements the song_index by one, with optional wrapping

interrupt()

stops current song without exiting the player. Will default to having the same effect as .next(), not advised unless you know what youre doing

is_alive()

returns true if vlc is either paused or playing

is_paused()

returns true if the player is paused, False if playing or if there is no song at all

mute()

mutes player and fades music out

next()

play next song in the queue

pause()

pauses the player

play(song, halting=False)

Play a single song

Parameters

  • song (str, Song) – keyword or url of a song on YouTube

  • halting (bool) – set to False to not halt the program

play_all(halting=False, **kwargs)

play entire song queue.

Parameters

  • halting (bool) – set to False to not halt the program exection

  • keep_alive (bool) – keep loop running even when the queue has ended, useful if you want to add more songs later (Note that this will halt indefinitely if halting=True. This will also have no effect if loop_queue = True and you plan on keeping it that way)

play_at_index(index, wrap=None)

plays the song at the given position in the queue

Parameters

  • index (int) – index of the song you want to play in the song queue

  • wrap (bool, None) – wether or not to modulo the index over the song queue. If set to None it will default to True only if Player.loop_queue is also True

play_current_song(*args, **kwargs)

play queue song at the current index

previous()

play previous song in the queue

remove_song(song_index: int)

Removes a song at the given index in the playlist

Parameters

song_index (int) – the index of the song you want to remove

scrub(seconds)

scrub the current song left or right in seconds

Parameters

seconds (int) – positive or negative int indicating seconds to fast forward/backwards

set_loop_queue(state: bool)

Changes the queue loop behavior. If set to True, the current queue will be restarted from the first song when the end is reached.

Parameters

state (bool) – whether to loop or not

set_progress(progress: float)

Set the progress of the currently playing song

Parameters

progress (float) – number between 0.0 and 1.0

set_volume(new_volume, fadetime=0.5, desync_volume=None)

change volume smoothly over fadetime seconds

Parameters

  • new_volume (int) – volume to transition to

  • fadetime (foat) – transition time in seconds

  • desync_volume (int) – don’t use this, its for muting

shuffle()

shuffle song queue

stop()

Stops player and exits

toggle_mute()

toggles between muted and unmuted player

toggle_pause()

toggles between paused and unpaused player

unmute()

unmutes player and fades music back in

unpause()

unpauses the player

update_rich_presence()

Update discord rich presence if self.rich_presence == True

wait_on_song_end()

waits until the current song has ended playing

wait_on_song_load()

waits until the current song is loaded

pYTerm.pYTerm.commandline()

Handles arguments if run from the commandline

pYTerm.pYTerm.get_args()

Parses argparse arguments from commandline and returns the namespace object mapped to the correct .play_all() and Player() kwargs

Tools module

The tools is full of extremely messy code that we banned to its own file so we dont have to look at it. It provides a bunch of functions to make the main player work more nicely without filling up the .py

pYTerm.tools.clear_line()

Clear current line

pYTerm.tools.clear_previous_line()

Clear previous line

pYTerm.tools.ensure_list(input_object)

Returns any input as a list. Tuples and sets get converted to lists, lists are returned as-is, and all other types get returned as a single element list

Parameters

input_object (any) – the object to get listified

pYTerm.tools.get_song_obj(song)

Create a song object from either a youtube url or a search query

Parameters

song (str) – the yt URL or search terms

pYTerm.tools.is_url(url)

Checks if a given string is an URL using regular expression, returns a bool (actually also returns true if its a path, so best coupled with is_youtube_url

pYTerm.tools.is_youtube_url(url)

Checks if a given string is a youtube url, returns a bool

class pYTerm.tools.mdict(startDict=None)

fucked up little multiple dict class made by yours truly :)

pYTerm.tools.previous_line()

Move cursor to previous line

pYTerm.tools.secs_to_string(seconds)

Gets time from seconds to human readable

pYTerm.tools.songs_from_yt_playlist(url)

Returns a list of song objects from a youtube playlist link

Parameters

urls (str) – url to a youtube playlist

pYTerm.tools.yt_playlist_to_rss_url(playlist_url)

Gets the rss url from a youtube playlist

backends module

The backends module provides a standardised way to integrate an audio backend with pYTerm. pYTerm currently has 2 audio backends:

  • VLCBackend, highly recommended but only works if your system has vlc media player installed

  • FFPyPlayerBackend, which works out of the box without any further installation, but is a lot less stable and prone to errors

class pYTerm.backends.AudioBackend(get_name, play, set_pause, set_volume, stop, is_paused, is_alive, get_current_time, get_total_time, get_volume, get_progress, set_progress, set_time)

AudioBackend provides a standardised way of integrating an audio backend in pYTerm. You can use the constructor on runtime to create backends on the fly, in case you want that for some reason, or you can implemenent all the functions under here

Parameters

  • get_name (callable) – function simply return the backend name as a str. If a song is already playing, stop it and play this one.

  • play (callable) – function to run when a song needs to be played, must accept a str argument of an audio URL

  • stop (callable) – called when the song needs to stop playing. Takes no arguments.

  • pause (callable) – called when pYTerm is paused or unpaused, must accept a bool argument indicating the pause state, where True is paused and False is unpaused

  • set_volume (callable) – called when volume needs to be changed, must accept an int argument indicating the volume level, where 0 is silent. Note that an int bigger than 100 may be given, if the backend doesnt support this make sure to clamp the number.

  • is_paused (callable) – must return True if the player is paused, or False if the player is unpaused

  • is_alive (callable) – must return True if the player is capable of playing music at this moment: it is either playing or paused. Return False if the backend isn’t capable of doing that at this time, for example if it’s not been given audio yet, or still loading a song. Rule of thumb is: return false if its not playing or paused (alternatively: return false if calling any of the other functions might raise an exception due to the current state of the backend.)

  • get_current_time (callable) – return the elapsed play time of the current song in ms as int. if no song is playing, you can return 0

  • get_total_time (callable) – return the total play time of the current song in ms as int. if no song is playing, you can return 0

  • get_volume (callable) – return the current backend volume as int, where 0 is lowest and 100 is considered “normal max volume”, although you are allowed to exceed this.

  • get_progress (callable) – return the current progress within a song as a float between 0.0 and 1.0. For example: the song is currently midway through playing: return 0.5. This may be calculated from the get_total_time and get_current_time, or the other way around. you can return 0.0 if is_alive is False

  • set_progress (callable) – set the backend’s progress of the current song to the given progress (a float between 0.0 and 1.0) where 0.0 is the start of the song and 1.0 is the end. A valueError may be raised if the float exceeds these bounds or is_alive is False.

  • set_time (callable) – set the current song elapsed time to x milliseconds. Must take an argument of type int as the milliseconds. If the backend doesn’t support this it can be calculated with get_total_time and passed to set_progress, or the other way around.

class pYTerm.backends.FFPyPlayerBackend

FFPyPlayer audio backend for pYTerm. Experimental and unstable, but requires no extra installation

class pYTerm.backends.VLCBackend

VLC audio backend for pYTerm. Highly recommended but requires VLC media player to be installed

pYTerm.backends.get_best_backend()

returns a AudioBackend instance thats deemed best for the system