multimedia_paradise 1.1.344

data/lib/multimedia_paradise/audio/audio_player/audio_player.rb

@@ -0,0 +1,1143 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === MultimediaParadise::AudioPlayer
+#
+# This is an "audio player".
+#
+# In other words - it plays audio files.
+#
+# For this to work, it distinguishes between different playmodes as will
+# be explained here.
+#
+# - If the argument given is an existing audio file, we will play it, then
+#   exit.
+#
+# - If we pass an array of files, we will store this array in our playlist
+#   and play all of them before we will then exit.
+#
+# - If we omit any argument then we will default to a neverending 'loop'.
+#   This also is the case when we pass 'loop' or nil as argument. Note
+#   that the loop is not unlimited; it will honour a threshold determined
+#   by an instance variable.
+#
+# - If we pass 'once', then we will play all audio files, and
+#   then exit.
+#
+# - If we pass 'one' or 'rand' as argument, we will play one
+#   random song, only ONCE, and then quit.
+#
+# - If we pass 'one_song', then we will play only this song.
+#
+# - If we pass in a number such as '3' then we will assume
+#   that the user wants to play exactly 3 files.
+#
+# Usage example:
+#
+#   MultimediaParadise::AudioPlayer.new(ARGV)
+#
+# =========================================================================== #
+# require 'multimedia_paradise/audio/audio_player/audio_player.rb'
+# =========================================================================== #
+require 'multimedia_paradise/audio/base.rb'
+
+module MultimediaParadise
+
+class AudioPlayer < AudioBase # === MultimediaParadise::AudioPlayer
+
+  begin
+    require 'x/tools/mrxvt_options.rb'
+  rescue LoadError; end
+
+  begin
+    require 'roebe/classes/kde/kde_konsole/kde_konsole.rb'
+  rescue LoadError; end
+
+  begin
+    require 'x/audio/playlist_profile.rb' # PlaylistProfile is declared here.
+  rescue LoadError; end # bl $RUBY_AUD/playlist_profile.rb
+
+  require 'multimedia_paradise/multimedia/play_from_this_list.rb'
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === MY_SONGS
+  # ========================================================================= #
+  MY_SONGS = AUDIO_DIRECTORY
+    AUDIO_DIR = MY_SONGS # === AUDIO_DIR
+
+  # ========================================================================= #
+  # === RENAME_KDE_KONSOLE_TAB
+  # ========================================================================= #
+  RENAME_KDE_KONSOLE_TAB = true
+
+  # ========================================================================= #
+  # === DEFAULT_DELAY_PLAYING_SONGS
+  #
+  # The following constant is used for determining the audio delay between
+  # two songs.
+  #
+  # A value of 0.0 would mean no delay, aka "instant play", logically. 
+  # ========================================================================= #
+  DEFAULT_DELAY_PLAYING_SONGS = 1.8
+
+  # ========================================================================= #
+  # === MAIN_AUDIO_PLAYER_TO_USE
+  #
+  # The entry of this constant will become the instance variable
+  # @audio_player_to_use.
+  #
+  # As of May 2015 we can dynamically set this.
+  # ========================================================================= #
+  _ = "#{::MultimediaParadise.project_yaml_dir?}video/video.yml"
+  if File.exist? _
+    _ = YAML.load_file(_)
+    if _.has_key? 'MAIN_VIDEO_PLAYER'
+      MAIN_AUDIO_PLAYER_TO_USE = _['MAIN_VIDEO_PLAYER']
+    end
+  else # We default to mpv since as of 2021.
+    MAIN_AUDIO_PLAYER_TO_USE = 'mpv' # mplayer'
+  end
+
+  # ========================================================================= #
+  # === LAST_SONG_PLAYED
+  # ========================================================================= #
+  LAST_SONG_PLAYED = 'LAST_SONG_PLAYED.md'
+
+  # ========================================================================= #
+  # === USE_OSS_FOR_AUDIO_PLAYER
+  # ========================================================================= #
+  USE_OSS_FOR_AUDIO_PLAYER = false
+
+  # ========================================================================= #
+  # === FULL_LOCATION_FOR_LAST_SONG_PLAYED
+  # ========================================================================= #
+  FULL_LOCATION_FOR_LAST_SONG_PLAYED = HOME+LAST_SONG_PLAYED # Specify the path to our file here.
+
+  # ========================================================================= #
+  # === MAXIMUM_ALLOWED_FILE_SIZE
+  # ========================================================================= # 
+  MAXIMUM_ALLOWED_FILE_SIZE = 1_350_000 # Shall not become larger than that, else we remove the file "last song played".
+
+  # ========================================================================= #
+  # === DEFAULT_PLAYMODE
+  # ========================================================================= #
+  DEFAULT_PLAYMODE = 'once'
+
+  # ========================================================================= #
+  # === NAME_OF_AUDIO_PLAYER
+  # ========================================================================= #
+  NAME_OF_AUDIO_PLAYER = 'AudioPlayer' # The name of the audio player.
+
+  # ========================================================================= #
+  # === PLAY_MAX_N_SONGS
+  # ========================================================================= #
+  PLAY_MAX_N_SONGS = 1250 # We won't play more than n songs.
+
+  # ========================================================================= #
+  # === USE_FAVOURITE_PLAYLIST
+  # ========================================================================= #
+  USE_FAVOURITE_PLAYLIST = false # If true we play only songs from this list
+
+  # ========================================================================= #
+  # === AVAILABLE_SONGS
+  #
+  # Obtain all available songs - and shuffle them a bit.
+  # ========================================================================= #
+  AVAILABLE_SONGS = Dir["#{MY_SONGS}*"].shuffle
+
+  # ========================================================================= #
+  # === SHALL_WE_DEBUG
+  # ========================================================================= #
+  SHALL_WE_DEBUG = false # If true we output debug info
+
+  # ========================================================================= #
+  # === PLAYLIST_CONSTANTS
+  #
+  # Whether we have the PlaylistProfile defined or not. If we have, we will
+  # make use of it.
+  # ========================================================================= #
+  if Object.const_defined? :PlaylistProfile
+    PLAYLIST_CONSTANTS = PlaylistProfile.constants
+  end
+
+  # ========================================================================= #
+  # === THE_LOG_FILE_IS_STORED_HERE
+  # ========================================================================= #
+  THE_LOG_FILE_IS_STORED_HERE =
+    "#{MultimediaParadise.log_dir?}"\
+    "log_file_for_played_songs_via_the_audio_player.md"
+
+  require 'multimedia_paradise/requires/require_file_duration.rb'
+  # ========================================================================= #
+  # === obtain_file_duration_from_this_file(i)
+  # ========================================================================= #
+  def obtain_file_duration_from_this_file(i)
+    MultimediaParadise::FileDuration[i]
+  end
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      i           = nil,
+      run_already = true
+    )
+    register_sigint { :pretty }
+    reset
+    if i
+      i = set_commandline_options_and_return_the_other_options(i)
+      menu(i)
+    end
+    case run_already
+    # ======================================================================= #
+    # === :dont_run_yet
+    # ======================================================================= #
+    when :dont_run_yet,
+         :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    clear_playlist
+    set_delay # Set @delay here.
+    set_shall_we_exit
+    infer_the_namespace
+    # ======================================================================= #
+    # === @use_colours
+    # ======================================================================= #
+    @use_colours = true # If true then we will use colours.
+    # ======================================================================= #
+    # === @main_colour
+    # ======================================================================= #
+    @main_colour = Colours.parse('green')
+    # ======================================================================= #
+    # === @play_in_a_loop
+    # ======================================================================= #
+    @play_in_a_loop = false
+    determine_which_audio_player_to_use
+    # ======================================================================= #
+    # === @debug
+    # ======================================================================= #
+    @debug = SHALL_WE_DEBUG
+    # ======================================================================= #
+    # === @hash_songs_played
+    # ======================================================================= #
+    @hash_songs_played = {} # We keep track of all the files that we played.
+    # ======================================================================= #
+    # === @play_max_n_songs
+    # ======================================================================= #
+    @play_max_n_songs = PLAY_MAX_N_SONGS # Safeguard.
+    if Object.const_defined? :MrxvtOptions
+      @mrxvt = MrxvtOptions.new
+    else
+      @mrxvt = nil
+    end
+    # ======================================================================= #
+    # === @use_oss_for_audio_player
+    # ======================================================================= #
+    @use_oss_for_audio_player = USE_OSS_FOR_AUDIO_PLAYER
+    # ======================================================================= #
+    # === @file_duration_in_seconds
+    # ======================================================================= #
+    @file_duration_in_seconds = 0 # Keeps the duration of the file in question.
+    # ======================================================================= #
+    # === @n_songs_played
+    # ======================================================================= #
+    @n_songs_played = 0 # How many songs we already played.
+    # ======================================================================= #
+    # === @available_genres
+    # ======================================================================= #
+    @available_genres = nil # Default.
+    @available_genres = PLAYLIST_CONSTANTS.map {|song|
+      song.to_s.sub(/GOOD_/,'').
+                sub(/_SONGS/,'').
+                sub(/MY_/,'').
+                sub(/CURRENT_/,'')
+    } if defined? PLAYLIST_CONSTANTS
+  end
+
+  # ========================================================================= #
+  # === determine_which_audio_player_to_use
+  #
+  # This method will determine which audio play is to be used, for playing
+  # the audio files. Currently the two primary ones that I use are mplayer
+  # and mpv. Note that the environment variable MAIN_AUDIO_PLAYER can
+  # overrule this completely, if set.
+  # ========================================================================= #
+  def determine_which_audio_player_to_use(
+      i                                        = MAIN_AUDIO_PLAYER_TO_USE,
+      overrule_if_environment_variable_was_set = true
+    )
+    case overrule_if_environment_variable_was_set
+    # ======================================================================= #
+    # === :ignore_environment_variable
+    # ======================================================================= #
+    when :ignore_environment_variable
+      overrule_if_environment_variable_was_set = false
+    end
+    case i
+    # ======================================================================= #
+    # === sox
+    # ======================================================================= #
+    when 'sox',
+         :sox
+      i = 'play' # The binary from sox is actually called "play", hence this line.
+    end
+    if overrule_if_environment_variable_was_set
+      if ENV.has_key? 'MAIN_AUDIO_PLAYER'
+        i = ENV['MAIN_AUDIO_PLAYER'].to_s.dup
+      end
+    end
+    @audio_player_to_use = i.to_s # Which audio player to use.
+  end
+
+  # ========================================================================= #
+  # === report_which_audio_player_to_use
+  # ========================================================================= #
+  def report_which_audio_player_to_use
+    opne 'The audio player '+sfancy(@audio_player_to_use)+
+         ' will be used.'
+  end
+
+  # ========================================================================= #
+  # === show_startup_message
+  #
+  # Display a fancy startup message.
+  # ========================================================================= #
+  def show_startup_message
+    e N+main_colour?+' => Starting Audio Player '+
+      simp(use_which_audio_player?)+main_colour?+' ('+
+      sfancy('Default delay: ')+delay?+mcol?+').'+N
+  end
+
+  # ========================================================================= #
+  # === set_commandline_options_and_return_the_other_options
+  # ========================================================================= #
+  def set_commandline_options_and_return_the_other_options(i)
+    unless i.is_a? Symbol
+      if i.respond_to?(:any?) and i.any? {|line|
+          line.start_with? '--'
+        }
+        @commandline_options = i.select {|inner_line|
+          inner_line.start_with? '--'
+        }
+        menu(@commandline_options)
+        # ===================================================================== #
+        # And finally, remove these entries that were found.
+        # ===================================================================== #
+        i.reject! {|entry|
+          entry.start_with? '--'
+        }
+      end
+    end
+    i
+  end
+
+  # ========================================================================= #
+  # === populate_hash_songs_played
+  #
+  # Fills up our hash with available data for the first time.
+  # Basically right now, only manipulates @hash_songs_played
+  # ========================================================================= #
+  def populate_hash_songs_played
+    playlist?.each { |song|
+      song = File.basename(song)
+      @hash_songs_played[song] = 0
+    }
+  end
+
+  # ========================================================================= #
+  # === set_delay
+  #
+  # This sets the default delay, when playing the audio songs in
+  # a loop.
+  # ========================================================================= #
+  def set_delay(i = DEFAULT_DELAY_PLAYING_SONGS)
+    @delay = i
+  end
+
+  # ========================================================================= #
+  # === get_file_size
+  # ========================================================================= #
+  def get_file_size(
+      of_this_file = the_songs_played_will_be_stored_where?
+    )
+    size = 0
+    size = File.size(of_this_file) if File.exist?(of_this_file)
+    size
+  end
+
+  # ========================================================================= #
+  # === set_shall_we_exit
+  # ========================================================================= #
+  def set_shall_we_exit(i = true)
+    @shall_we_exit = i
+  end
+
+  # ========================================================================= #
+  # === show_available_genres
+  # ========================================================================= #
+  def show_available_genres
+    opne 'The available genres are:'
+    pp @available_genres
+  end
+
+  # ========================================================================= #
+  # === shall_we_exit?
+  # ========================================================================= #
+  def shall_we_exit?
+    @shall_we_exit
+  end
+
+  # ========================================================================= #
+  # === show_last_file_played
+  #
+  # This method will show the last song played.
+  # ========================================================================= #
+  def show_last_file_played(
+      _ = the_songs_played_will_be_stored_where?
+    )
+    if File.exist? _
+      e 'The last song played was:'
+      efancy('  '+File.readlines(_)[-1])
+      exit_program
+    else
+      ewarn 'But the file '+sfile(_)+RED+' does not exist.'
+    end
+  end
+
+  # ========================================================================= #
+  # === the_songs_played_will_be_stored_where?
+  # ========================================================================= #
+  def the_songs_played_will_be_stored_where?
+    FULL_LOCATION_FOR_LAST_SONG_PLAYED
+  end
+
+  # ========================================================================= #
+  # === add_random_song
+  #
+  # This will add exactly one random song.
+  # ========================================================================= #
+  def add_random_song
+    add_song(return_random_song)
+  end
+
+  # ========================================================================= #
+  # === shuffle_the_playlist
+  # ========================================================================= #
+  def shuffle_the_playlist
+    playlist?.shuffle!
+  end; alias shuffle shuffle_the_playlist # shuffle
+
+  # ========================================================================= #
+  # === do_play_in_a_loop
+  # ========================================================================= #
+  def do_play_in_a_loop
+    @play_in_a_loop = true
+  end
+      
+  # ========================================================================= #
+  # === try_to_play_playlist
+  # ========================================================================= #
+  def try_to_play_playlist
+    begin
+      require 'x/AUD/playlist.rb'
+      add(Playlist.playlist?)
+      shuffle
+    rescue LoadError; end
+  end
+
+  # ========================================================================= #
+  # === show_the_playlist
+  # ========================================================================= #
+  def show_the_playlist
+    opne 'The playlist is:'
+    pp playlist?
+  end; alias show_songs show_the_playlist # === show_songs
+
+  # ========================================================================= #
+  # === main_colour?
+  # ========================================================================= #
+  def main_colour?
+    @main_colour
+  end; alias mcol? main_colour? # mcol?
+
+  # ========================================================================= #
+  # === return_all_songs
+  #
+  # By default, we will shuffle.
+  # ========================================================================= #
+  def return_all_songs
+    return AVAILABLE_SONGS.shuffle
+  end; alias all_songs                 return_all_songs # === all_songs
+       alias get_all_songs             return_all_songs # === get_all_songs
+       alias determine_available_songs return_all_songs # === determine_available_songs
+       alias all_songs?                return_all_songs # === all_songs?
+
+  # ========================================================================= #
+  # === return_random_song
+  #
+  # This method will return one random song.
+  # ========================================================================= #
+  def return_random_song
+    return_all_songs.first
+  end; alias fetch_random_song return_random_song
+       alias get_random_song   return_random_song
+
+  # ========================================================================= #
+  # === reset_playlist
+  # ========================================================================= #
+  def reset_playlist
+    @array_play_these_songs = [] # Keep all files that we wish to play in this Array.
+  end; alias clear_playlist reset_playlist
+
+  # ========================================================================= #
+  # === audio_dir?
+  # ========================================================================= #
+  def audio_dir?
+    AUDIO_DIR
+  end
+
+  # ========================================================================= #
+  # === register_this_song
+  #
+  # This method should be invoked whenever you want to play a new song.
+  #
+  # We will only keep the filename, not the full location.
+  # ========================================================================= #
+  def register_this_song(this_song)
+    if @hash_songs_played
+      this_song = File.basename(this_song)
+      if @hash_songs_played.has_key? this_song
+        @hash_songs_played[this_song] = @hash_songs_played[this_song] + 1
+      else
+        @hash_songs_played[this_song] = 1 # Initialize at 1 then.
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === add_all_songs
+  # ========================================================================= #
+  def add_all_songs
+    add(all_songs?)
+  end
+
+  # ========================================================================= #
+  # === refresh_playlist
+  #
+  # First clears the playlist, then adds all available songs.
+  # ========================================================================= #    
+  def refresh_playlist
+    clear_playlist
+    add_all_songs
+  end
+
+  # ========================================================================= #
+  # === perform_cleanup
+  #
+  # We get rid of @ivars which are not too useful.
+  # ========================================================================= #
+  def perform_cleanup
+    remove_instance_variable :@available_genres
+  end
+
+  # ========================================================================= #
+  # === check_whether_the_song_directory_is_empty
+  # ========================================================================= #
+  def check_whether_the_song_directory_is_empty
+    if return_all_songs.empty?
+      opne 'No songs found in `'+sdir(audio_dir?)+'`.'
+      opne 'Perhaps you forgot to copy some songs first?'
+      exit_program(:force_exit)
+    end
+  end
+
+  # ========================================================================= #
+  # === exit_program
+  #
+  # This method can be used to exit this program.
+  # ========================================================================= #
+  def exit_program(
+      shall_we_exit = shall_we_exit?,
+      be_verbose    = true,
+      &block
+    )
+     
+    case shall_we_exit
+    # ======================================================================= #
+    # === :force_exit
+    # ======================================================================= #
+    when :force_exit
+      shall_we_exit = true
+    # ======================================================================= #
+    # === :force_exit_but_be_quiet
+    # ======================================================================= #
+    when :force_exit_but_be_quiet
+      shall_we_exit = true
+      be_verbose = false
+    end
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_quiet
+      # ===================================================================== #
+      when :be_quiet
+        be_verbose = false
+      end
+    end
+    if shall_we_exit
+      @mrxvt.set_title('') if @mrxvt
+      if be_verbose
+        efancy 'Leaving ...'
+        efancy 'Hopefully you had fun and found class'\
+               'MultimediaParadise::AudioPlayer useful. Bye!'
+      end
+      consider_resetting_kde_konsole_tab
+      exit
+    else
+      e "Won't exit as we are not allowed to exit."
+    end
+  end
+
+  # ========================================================================= #
+  # === input?
+  # ========================================================================= #
+  def input?
+    @array_play_these_songs
+  end; alias play_these_songs input? # === play_thse_songs
+       alias playlist?        input? # === playlist?
+
+  # ========================================================================= #
+  # === sanitize_songs
+  # ========================================================================= #
+  def sanitize_songs
+    playlist?.flatten! # Always flatten it afterwards.
+  end
+
+  # ========================================================================= #
+  # === add_song                                                    (add tag)
+  #
+  # This method will add the particular song to the playlist.
+  #
+  # It will check whether it is an multimedia-file prior to adding it,
+  # though.
+  # ========================================================================= #
+  def add_song(
+      i = nil
+    )
+    unless i.nil?
+      [i].flatten.compact.each {|this_song|
+        if is_a_multimedia_file?(this_song)
+          @array_play_these_songs << this_song
+        end
+      }
+      sanitize_songs
+    end
+  end; alias add                       add_song # === add
+       alias add_to_playlist           add_song # === add_to_playlist
+       alias add_this_song_to_playlist add_song # === add_this_song_to_playlist
+       alias add_this_song             add_song # === add_this_song
+       alias add_songs                 add_song # === add_songs
+
+  # ========================================================================= #
+  # === register_sigint
+  #
+  # Will act upon SIGINT recieved, and properly shut down.
+  # ========================================================================= #
+  def register_sigint
+    Signal.trap('SIGINT') {
+      consider_resetting_kde_konsole_tab
+      exit_program(true)
+    }
+  end
+
+  # ========================================================================= #
+  # === consider_resetting_kde_konsole_tab
+  #
+  # This method can be used to re-set the KDE konsole tab name.
+  # ========================================================================= #
+  def consider_resetting_kde_konsole_tab(
+      use_this_as_the_new_title = '.'
+    )
+    do_rename_konsole(
+      use_this_as_the_new_title, RENAME_KDE_KONSOLE_TAB
+    )
+  end
+
+  # ========================================================================= #
+  # === try_to_find_genre_song
+  #
+  # This tries to find a (random) genre song.
+  # ========================================================================= #
+  def try_to_find_genre_song(i)
+    upcased = i.to_s.upcase
+    if @available_genres.grep(/#{upcased}/)
+      matches = PLAYLIST_CONSTANTS.select {|entry| entry =~ /#{upcased}/ }[0]
+      if matches.nil? # Then try without playlist
+        these_songs = Dir[audio_dir?+'*'+i+'*']
+      end
+      these_songs = PlaylistProfile.module_eval(matches.to_s).map {|entry|
+        audio_dir?+entry
+      } if matches
+      add_song(these_songs.shuffle)
+    end if @available_genres
+  end
+
+  # ========================================================================= #
+  # === pause                                                     (pause tag)
+  #
+  # Pause for n_seconds (the first input to this method).
+  #
+  # This method will NOT seet a new, random song - for this,
+  # you need to use another method.
+  # ========================================================================= #
+  def pause(
+      n_seconds = delay?
+    )
+    n_seconds = n_seconds.to_f # Always keep it as a float here.
+    cliner
+    e "#{true_rev}We will pause for #{sfancy(n_seconds)} #{rev}seconds."
+    cliner_with_time_stamp
+    e "#{rev}The next song will be: #{sfancy(playlist?[@n_songs_played])}"
+    cliner
+    sleep(n_seconds)
+  end
+
+  # ========================================================================= #
+  # === play_this_song                                             (play tag)
+  #
+  # This is the actual method that will play the song.
+  #
+  # We will also append the filename last played.
+  # ========================================================================= #
+  def play_this_song(
+      i, be_verbose = true
+    )
+    if be_verbose 
+      e; opne 'The next song we will play via '+
+                  simp(audio_player_to_use?)+' is:'
+      e "#{N}   #{sfancy(i)}#{N}#{N}"
+    end
+    # ======================================================================= #
+    # Next, act on .mp3 files.
+    # ======================================================================= #
+    if File.extname(i) == '.mp3'
+      begin
+        @file_duration_in_seconds = obtain_file_duration_from_this_file(i)
+        if be_verbose
+          e "#{rev}The length of this song is: "+
+            sfancy(@file_duration_in_seconds.to_i)+rev+' seconds.'
+        end
+      rescue Exception => error
+        e error
+      end
+    end
+    e "  #{sfile(i)}" if be_verbose
+    consider_renaming_the_kde_konsole_tab(i)
+    _ = audio_player?.dup
+    _ << ' -ao oss' if @use_oss_for_audio_player
+    _ << ' '+i.dup
+    # ======================================================================= #
+    # Register which song was played. We do this before we actually play
+    # the song.
+    # ======================================================================= #
+    register_which_song_will_be_played_next(i)
+    esystem _
+    @n_songs_played += 1
+  end
+
+  # ========================================================================= #
+  # === do_rename_konsole
+  # ========================================================================= #
+  def do_rename_konsole(
+      i = '.', *optional_arguments_that_are_irrelevant
+    )
+    if Object.const_defined? :Roebe
+      Roebe.rename_konsole(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === store_data_about_this_song_into_a_local_file
+  # ========================================================================= #
+  def store_data_about_this_song_into_a_local_file(
+      this_song
+    )
+    into = THE_LOG_FILE_IS_STORED_HERE
+    what = "song name: #{this_song.ljust(30)}, "\
+           "played on #{dd_mm_yyyy}, #{hh_mm_ss}\n"
+    dirname = File.dirname(into)
+    mkdir(dirname) unless File.directory? dirname
+    append_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === show_the_log_file_if_it_exists
+  #
+  # Invocation example:
+  #
+  #   rsong --log?
+  #
+  # ========================================================================= #
+  def show_the_log_file_if_it_exists(
+      log_file = THE_LOG_FILE_IS_STORED_HERE
+    )
+    if File.exist? log_file
+      opne 'Displaying the content of the file at'
+      opne '`'+sfile(log_file)+'`:'
+      dataset = File.readlines(log_file).map {|entry| entry.rstrip } 
+      e
+      e mediumpurple(
+          dataset.map {|entry| "  #{entry}" }.join("\n")
+        )
+    else
+      opne 'No file exists at '+sfile(log_file)+'.'
+    end
+  end
+
+  # ========================================================================= #
+  # === audio_player_to_use?
+  # ========================================================================= #
+  def audio_player_to_use?
+    @audio_player_to_use
+  end; alias audio_player?           audio_player_to_use? # === audio_player?
+       alias use_which_audio_player? audio_player_to_use? # === use_which_audio_player?
+
+  # ========================================================================= #
+  # === delay?
+  # ========================================================================= #
+  def delay?
+    @delay.to_s
+  end
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # Show help here, then exit.
+  # ========================================================================= #
+  def show_help(
+      optional_shall_we_exit = false
+    )
+    cliner
+    opne 'Showing the available help options next:'
+    e
+    colourized_comment '  - OPEN        # open this file in the editor'
+    colourized_comment '  - loop        # play in an eternal loop'
+    colourized_comment '  - rand        # play one random song'
+    colourized_comment '  - once        # play all songs once, then quit'
+    colourized_comment '  - last?       # show the last song played'
+    colourized_comment '  - player?     # show which multimedia-player we will use'
+    colourized_comment '  - log?        # show the log file of last-songs-played (if this file exists)'
+    colourized_comment '  - last-songs? # show the last songs that '\
+                       'were played, in a time-sorted manner'
+    e
+    cliner
+    exit_program(true, false) if optional_shall_we_exit == :then_exit
+  end
+
+  # ========================================================================= #
+  # === play_the_playlist
+  # ========================================================================= #
+  def play_the_playlist
+    if @play_in_a_loop # We wish to play in a never-ending loop.
+      counter = 0
+      loop {
+        playlist?.each {|song|
+          play_this_song(song)
+          pause unless @n_songs_played == playlist?.size
+          counter += 1
+          break if counter > @play_max_n_songs
+        }
+        refresh_playlist
+      }
+    else
+      playlist?.each {|song|
+        play_this_song(song)
+        pause unless @n_songs_played == playlist?.size
+      } # Afterwards, we will have exited.
+    end
+  end
+
+  # ========================================================================= #
+  # === register_which_song_was_last_played
+  #
+  # This method will also check if the file that is being played is too
+  # big. If it is, we will remove the log-file.
+  # ========================================================================= #
+  def register_which_song_was_last_played(
+      this_song,
+      store_where_to = the_songs_played_will_be_stored_where?
+    )
+    $stdout.flush # Unsure why we wish to do this.
+    FileUtils.touch(store_where_to) unless File.exist?(store_where_to)
+    if get_file_size(store_where_to) > MAXIMUM_ALLOWED_FILE_SIZE
+      remove_file(store_where_to)
+    end
+    unless store_where_to.include? '/'
+      store_where_to = HOME_DIRECTORY+store_where_to
+    end # store_where_to now defaults to: /root/LAST_SONG_PLAYED
+    append_what_into(this_song+N, store_where_to)
+    register_this_song(this_song)
+    # ======================================================================= #
+    # Since as of September 2021 this class will also try to store into
+    # a log file, if possible.
+    # ======================================================================= #
+    store_data_about_this_song_into_a_local_file(this_song)
+  end; alias register_which_song_will_be_played_next register_which_song_was_last_played # === register_which_song_will_be_played_next
+
+  # ========================================================================= #
+  # === show_the_last_songs_that_were_played
+  #
+  # The songs played will be stored in a .md file.
+  #
+  # Invocation example:
+  #
+  #   rsong --last-songs?
+  #
+  # ========================================================================= #
+  def show_the_last_songs_that_were_played
+    _ = the_songs_played_will_be_stored_where?
+    if File.exist? _
+      dataset = File.readlines(_)
+      dataset.each {|this_song| e steelblue(this_song.strip) }
+    else
+      no_file_exists_at(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_renaming_the_kde_konsole_tab
+  # ========================================================================= #
+  def consider_renaming_the_kde_konsole_tab(i)
+    # ======================================================================= #
+    # === Rename the KDE Konsole tab here
+    # ======================================================================= #
+    if Object.const_defined? :Roebe
+      begin
+        i = File.basename(i).
+            gsub(/#{File.extname(i)}$/,'').
+            tr('_',' ')
+      # ===================================================================== #
+      # Must rescue this, in case of errors such as:
+      #   invalid byte sequence in UTF-8
+      # ===================================================================== #
+      rescue ArgumentError => error
+        opne 'An error happened (ArgumentError) which is now displayed:'
+        pp error
+      end
+      Roebe.rename_konsole(i)
+    end if RENAME_KDE_KONSOLE_TAB
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(i)
+    if i.is_a? Array
+      if i.empty?
+        i = 'loop'
+      else
+        i = i.join(' ').strip
+      end
+    end
+    i = i.to_s.strip
+    if i =~ /^\d+$/ # If input consists of only numbers.
+      opnn; e 'We will next play '+simp(i.to_s)+' songs.'
+      i.to_i.times { add_random_song }
+    # ======================================================================= #
+    # === 11:22:33
+    #
+    # Handle time-formats next.
+    # ======================================================================= #
+    elsif i =~ /^\d{1,2}:\d{1,2}:\d{1,2}$/ # If input consists of only numbers and ':'.
+      # ===================================================================== #
+      # User did input a time format such as "11:22:33". We will assume this
+      # to mean to enter idle mode, and then play the songs via a loop.
+      # ===================================================================== #
+      begin
+        require 'roebe/classes/at.rb'
+        Roebe::At.new(i)
+        do_play_in_a_loop # We play in a loop in this case.
+      rescue LoadError
+        e 'The file roebe/classes/at.rb is not available.'
+      end
+    else
+      case i # case tag
+      # ===================================================================== #
+      # === help
+      #
+      # This entry point can be used to show the help section.
+      # ===================================================================== #
+      when *ARRAY_HELP_OPTIONS
+        show_help :then_exit
+      # ===================================================================== #
+      # === rsong --last-songs?
+      # ===================================================================== #
+      when /^-?-?last(-|_)?songs\??$/i
+        show_the_last_songs_that_were_played
+        exit_program { :be_quiet }
+      # ===================================================================== #
+      # === --use-sox
+      # ===================================================================== #
+      when /^-?-?use(-|_)?sox/
+        determine_which_audio_player_to_use(
+          :sox, :ignore_environment_variable
+        )
+      # ===================================================================== #
+      # === --use-mplayer
+      # ===================================================================== #
+      when /^-?-?use(-|_)?mplayer/
+        determine_which_audio_player_to_use(
+          :mplayer, :ignore_environment_variable
+        )
+      # ===================================================================== #
+      # === rsong --log?
+      # ===================================================================== #
+      when /^-?-?log\??$/i
+        show_the_log_file_if_it_exists
+        exit_program(:force_exit_but_be_quiet)
+      # ===================================================================== #
+      # === OPEN
+      # ===================================================================== #
+      when /^-?-?OPEN$/i
+        esystem "bluefish #{__FILE__}"
+        exit_program(:force_exit)
+      # ===================================================================== #
+      # === rsong --player?
+      # ===================================================================== #
+      when /^-?-?player\??$/
+        report_which_audio_player_to_use
+        exit_program { :be_quiet }
+      # ===================================================================== #
+      # === random
+      # ===================================================================== #
+      when 'random',
+           'return_random_song',
+           'rand',
+           'one' # Only add one song.
+        add_random_song
+      # ===================================================================== #
+      # === chill
+      # ===================================================================== #
+      when 'list','chill','1'
+        if Object.const_defined? :PlaylistProfile
+          these_songs = PlaylistProfile::GOOD_CHILL_SONGS.map {|entry|
+            audio_dir?+entry
+          }
+          add(these_songs.shuffle)
+        end
+      # ===================================================================== #
+      # === playlist
+      # ===================================================================== #
+      when /playlist\??/i
+        try_to_play_playlist
+      # ===================================================================== #
+      # === last?
+      # ===================================================================== #
+      when 'last?'
+        show_last_file_played
+      # ===================================================================== #
+      # === once
+      # ===================================================================== #
+      when 'once','noloop','default','all', # This means we play every song exactly once, then quit.
+           '','true','false',
+           'all_songs',
+           'play_all_songs'
+        opnn; e 'We will play all available Audio files once.'
+        add_all_songs
+      # ===================================================================== #
+      # === dance
+      # ===================================================================== #
+      when 'dance','bdance','breakdance' # Im Moment hardcoded auf bdance
+        these_songs = PlaylistProfile::GOOD_BDANCE_SONGS.shuffle.map {|entry|
+          audio_dir?+entry
+        }
+        add(these_songs.shuffle)
+      # ===================================================================== #
+      # === loop
+      # ===================================================================== #
+      when 'loop','l','nil'
+        # Notify the user what we are doing next.
+        opnn; e "#{main_colour?}Playing in a neverending #{sfancy('loop')}"\
+                "#{main_colour?} next:"
+        do_play_in_a_loop
+      # ===================================================================== #
+      # === genre
+      # ===================================================================== #
+      when 'genre','GENRES','genres','GENRE'
+        unless ARGV[1]
+          show_available_genres
+          exit_program(:force_exit)
+        end
+      else # else tag
+        # =================================================================== #
+        # Grab all entries from the current directory that can match to the
+        # input.
+        # =================================================================== #
+        entries = Dir['*'+i+'*']
+        unless entries.empty?
+          add_songs(entries)
+        else
+          try_to_find_genre_song(i)
+        end
+      end
+    end
+  end; alias check_against_menu menu # === check_against_menu
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    populate_hash_songs_played
+    show_startup_message
+    check_whether_the_song_directory_is_empty
+    play_the_playlist
+    perform_cleanup
+  end
+
+end
+
+# =========================================================================== #
+# === MultimediaParadise.audio_player
+#
+# We also want to use a simpler module-method for the audio player.
+# =========================================================================== #
+def self.audio_player(options = nil)
+  MultimediaParadise::AudioPlayer.new(options)
+end; self.instance_eval { alias audio_play audio_player } # === MultimediaParadise.audio_play
+     self.instance_eval { alias play       audio_player } # === MultimediaParadise.play
+     self.instance_eval { alias []         audio_player } # === MultimediaParadise[]
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # pp MultimediaParadise::AudioPlayer
+  _ = MultimediaParadise::AudioPlayer.new(ARGV, :dont_run_yet)
+  if ARGV[1]
+    _.try_to_find_genre_song(ARGV[1]) # To test this, try: rsong genre GOOD_BDANCE_SONGS
+  end
+  _.run
+end # rsong power
+    #
+    # If you do this:
+    #   rsong ELE
+    # We load all ELE songs in our playlist
+    #   rsong playlist
+    # Will play our playlist.