multimedia_paradise 1.1.344 → 1.2.2

data/doc/README.gen

@@ -4,79 +4,83 @@ DEFAULT_HEADER
 
 <img src="https://i.imgur.com/Qh4Fve1.png" style="margin: 1em; margin-left: 2.5em">
 
-The **multimedia paradise** project bundles together code that can be
-used for "multimedia data" - in particular for **audio** and **video** files.
-
-Most of the functionality found within the **multimedia paradise**
-projects depends on <b>ffmpeg</b>, but in principle the code in the
-main module called **MultimediaParadise** should work with other
-toolkits as well, if a toolkit supports certain actions (such as
-<b>sox</b>). As is often the case, support for other toolkits depends
-on time investment - and time availability - of the main author of
-this project, but in principle support for other toolkits can be
-added as-is, at any moment in time. It is just that **ffmpeg** is
-really good, so other toolkits will have a hard time competing
-against it.
-
-For multimedia-related purposes, **ffmpeg** is a really excellent
-project. Thus, the MultimediaParadise gem will focus on **ffmpeg**
+The <b>multimedia paradise</b> project bundles together code that can be
+used for "multimedia data" - in particular for <b>audio</b> and <b>video</b>
+files.
+
+Most of the functionality found within the <b>multimedia paradise</b>
+projects depends on the external project called <b>ffmpeg</b>. However had,
+in principle the code in the toplevel-module called <b>MultimediaParadise</b>
+should also work with other toolkits as well, provided that said toolkit
+supports certain actions - such as <b>sox</b> does.
+
+As is often the case, support for other toolkits depends on time investment
+though - and time availability - of the main author of this project. Nonetheless,
+whenever possible, support for other toolkits will be added as-is. It is 
+just that <b>ffmpeg</b> is really an excellent project, so other toolkits
+will have a hard time competing against <b>ffmpeg</b>.
+
+For multimedia-related purposes, <b>ffmpeg</b> can be recommended. Thus,
+the MultimediaParadise gem will also focus primarily on <b>ffmpeg</b>
 by default.
 
-You can obtain a copy of ffmpeg from the following URL:
+A copy of ffmpeg can be obtained from the following URL:
 
 https://www.ffmpeg.org/download.html
 
 ## Installation of the MultimediaParadise project
 
-There are several ways how to install this project, including using
-oldschool **setup.rb** - but I recommend the following way, for
-simplicity, on any modern system:
+There are several ways how to install the multimedia_paradise project. Personally
+I still use the oldschool way via <b>setup.rb</b>, but the more modern, and 
+recommend way, to install this gem goes via <b>gem install</b>, specifically:
 
     gem install multimedia_paradise --user-install
 
-The reason as to why I recommend the **--user-install** option is to be
-used is because the various files under the **bin/** subdirectory that
+The reason as to why it is recommended to use the <b>--user-install</b> option
+is because the various files under the <b>bin/</b> subdirectory that
 are part of this gem will be made available in your home directory
 (under e. g. ~/.gem/ruby/2.5.0/bin or whatever your local ruby
 version is). That way you can easily add that directory to $PATH
 or not, and make use of these files if you want to - and if not,
 just ignore the bin/ subdirectory of this gem altogether.
 
-You can find out the paths used by **gem** via:
+You can find out the paths used by <b>gem</b> by issuing the following
+command:
 
     gem environment
 
-Note that even if you can not find such a bin/ subdirectory on your
-system, these files are distributed within the **multimedia_paradise**
+Note that even if you can not find such a <b>bin/</b> subdirectory on your
+system, these files are distributed within the <b>multimedia_paradise</b>
 gem itself as such, so just extract the gem, then copy the bin/ files
-to wherever you want to. There is more than one way to do
-things! If you still have a hard time doing so, you can use a 
-toplevel method that will copy all bin/ files into the current
-working directory. So, for instance, create a directory at:
+to wherever you want to. There is more than one way to do things!
+
+If you still have a hard time doing so, you can use a toplevel method that
+will copy all bin/ files into the current working directory. So, for
+instance, create a directory at the following location:
 
     mkdir /tmp/multimedia_paradise # just an example
 
-Then start **irb** and issue:
+Then start <b>irb</b> and issue:
 
     require 'multimedia_paradise'
     MultimediaParadise.copy_bin_directory
 
-This will create a directory called **bin/** and then proceed
-to copy all bin/ files into that directory. This is just a
-convenience workaround if --user-dir does not work on your
-system, for whatever the reason. (Note that this assumes
-that these bin/ entries are in your HOME directory under
-bin/ which may not always be the case; I have no idea why
-this does not work anymore. It used to work in the past.
+This will create a directory called <b>bin/</b> and then proceed
+to copy all bin/ files that are distributed via the multimedia_paradise
+gem into that directory. This is just a convenience workaround if
+--user-dir does not work on your system, for whatever the reason.
+(Note that this assumes that these bin/ entries are in your HOME
+directory under bin/ which may not always be the case; I have no idea
+why this does not work anymore. It used to work in the past.
 Ask the rubygems maintainers what they broke over the
 years if this does not work for you. :P But, even in that
 case, you can just download the .gem file from rubygems.org
 and extract it on your own, and then you will 100% have
 the bin/ hierarchy there.)
 
-It is recommended to install **ffmpeg** and have it made
-available on your system - ffmpeg really is a great project,
-and the multimedia_paradise gem taps into the functionality
+It is also recommended to install <b>ffmpeg</b> and have it made
+available on the given computer system at hand - ffmpeg really is
+a great project, and the multimedia_paradise gem taps into the functionality
 made available by ffmpeg. In many ways the multimedia_paradise
 gem is a convenient wrapper over **some** of ffmpeg's 
 functionality.
@@ -91,11 +95,11 @@ not necessarily a professional-grade software suite.
 ## Removing the audio from a local video file
 
 Let us begin with a fairly simply use case here: say that you 
-want to **remove the audio from a local video file**.
+want to <b>remove the audio from a local video file</b>.
 
 So if you have such a use case that requires of you to
 **remove audio from a local video file**, use the
-following **API**:
+following <b>API</b>:
 
     require 'multimedia_paradise/audio/remove_audio.rb'
     MultimediaParadise.remove_audio(path_to_the_file_goes_in_here)
@@ -1623,7 +1627,7 @@ So, how to use class <b>MultimediaParadise::CreateM3uPlaylist</b>?
 
 The input to class <b>MultimediaParadise::CreateM3uPlaylist</b>
 should ideally be a **yaml file** describing your songs (at the
-least **the path to these songs**), but you could also use the **API**
+least **the path to these songs**), but you could also use the <b>API</b>
 from within Ruby, naturally and thus use a **ruby array** directly
 that is to be passed to the class; just pass this Array to
 **.new()**.
@@ -1915,14 +1919,14 @@ Usage example if you want to do only one image per second:
 
     MultimediaParadise.video_to_images("foobar.mp4", :default, 1)
 
-See the file **multimedia_paradise/toplevel_methods/conversion.rb**
+See the file <b>multimedia_paradise/toplevel_methods/conversions.rb</b>
 for more information about that functionality - it is made possible
 thanks to ffmpeg.
 
 ## Radio stations and a graphical user interface to it (GUI)
 
-Since as of **October 2018**, the **MultimediaParadise** project comes
-with a small **yaml file** called **radio_stations.yml**.
+Since as of <b>October 2018</b>, the **MultimediaParadise** project comes
+with a small **yaml file** called <b>radio_stations.yml</b>.
 
     x = YAML.load_file('radio_stations.yml')
 
@@ -2018,6 +2022,38 @@ It now looks like this:
 Not sure if this was an actual improvement, but for now it'll stay
 that way.
 
+## MultimediaParadise.action()
+
+The toplevel-method <b>MultimediaParadise.action()</b> was added
+during the March 2024 rewrite of the multimedia_paradise gem.
+
+The basic idea behind actions, implemented via the aforementioned
+method, is to bundle all activities that may seem useful to most
+users in a centralized manner.
+
+So, for instance: say that you wish to extract the audio from
+a given video file, via ffmpeg. The file at hand will be called
+<b>foobar.mp4</b>.
+
+You can generalize this via actions like in this way:
+
+    MultimediaParadise.action(:extract_audio, 'foobar.mp4')
+
+That's it!
+
+Of course the simpler method called
+<b>MultimediaParadise.action()</b> is also available, but
+the main benefit of MultimediaParadise.action() is that you
+do not have to require any specific file. You can ignore
+the file paths there, and just think in terms of
+actionable components. This is especially useful when we
+use MultimediaParadise in a GUI. It will simplify a lot
+of the GUI code past this point, which is why this is
+a win-win situation for the multimedia_paradise gem. I
+will eventually add java-swing components as well, thus
+allowing users to make use of the multimedia_paradise
+gem on windows as well. 
+
 ## Converting a .mp4 or .avi file to an animated .gif
 
 You can use the following API to convert a video to an
@@ -2599,7 +2635,7 @@ automatically create a thumbnail from a video file.
 
 Usage example:
 
-    require 'multimedia_paradise/toplevel_methods/misc.rb' # ← This file includes the code shown below.
+    require 'multimedia_paradise/toplevel_methods/toplevel_methods.rb' # ← This file includes the code shown below.
     this_file = '/Depot/j/foobar.mp4'
 
     MultimediaParadise.automatically_create_a_thumbnail_for_this_video()
@@ -2643,11 +2679,12 @@ by ffmpeg <b>does</b> work.
 
 ## Learning to play the piano
 
-Since a few months I am (again) learning to play the piano, although
-I use a Yamaha keyboard rather than a piano.
+Since early <b>2024</b> I am (again) learning to play the piano, although
+I use a <b>Yamaha keyboard</b> rather than a piano.
 
-This subsection here will collect various snippets that may relate
-to playing songs. This is very random though.
+This subsection here will collect various snippets that may relate to
+playing songs, including how to practice properly. This is very random,
+though, as it will change as I learn new things.
 
 Phantom of the Opera:
 

data/doc/{CHANGELOG.md → changelog/changelog.md}

@@ -3,15 +3,15 @@
 #
 # Note that since as of 2016, this changelog is barely updated anymore.
 #
-# Features are more important than listing when they may have been
-# added or changed. :)
+# Features are more important than listing when they may have been added
+# or changed. :)
 #
 #   when        | what
 # ---------------------------------------------------------------------------
 #
 #   22.02.2006:  Added audio_player.rb, yay! \o/
-#   24.02.2006:  Changed ARGV behaviour. Now the arg that is supplied
-#                will be the default file to use.
+#   24.02.2006:  Changed ARGV behaviour. Now the arg that is supplied will
+#                be the default file to use.
 #   10.03.2006:  Umount dvds has been added.
 #   09.08.2006:  Unified ways to exit the script.
 #   15.09.2006:  Added readline support, thus we are now able to scroll 
@@ -39,6 +39,8 @@
 #                code clean-up job) and increased the version to 1.1.0.
 #   08.06.2021:  Improved the sinatra-specific part of MultimediaParadise.
 #                It is now possible to play the registered video files
-#                via sinatra as well, even on windows. This was tested
-#                on that day also.
+#                via sinatra as well, even on windows. This was also tested
+#                on that very day.
+#   07.03.2024:  The multimedia_paradise gem was cleaned up and partially
+#                rewritten.
 # =========================================================================== #

data/doc/{LINKS.md → links/links.md}

@@ -1,6 +1,6 @@
 This file gathers some useful website resources about ffmpeg.
 
-The entries may become outdated quickly, though, as the www
-is very volatile:
+The entries may become outdated quickly, though, as the www is 
+very volatile:
 
   https://www.ostechnix.com/20-ffmpeg-commands-beginners/

data/doc/{MOTIVATION_FOR_THIS_PROJECT.md → motivation_for_the_multimedia_paradise_project/motivation_for_the_multimedia_paradise_project.md}

@@ -4,11 +4,11 @@ back then was called "multimedia" and the other project was called
 "videotools".
 
 I wanted to be able to manipulate audio and video data, and I found it
-increasingly difficult to reason why the two projects called "multimedia"
-and "videotools" were separate projects. This may not sound problematic
-to other people, but my brain had a hard time remembering where I put
-in code, and why it is only available there, but not in the other
-project as well.
+increasingly difficult to reason as to why the two projects called
+"multimedia" and "videotools" were separate projects. This may not sound
+problematic to other people, but my brain had a hard time remembering
+where I put in code, and why it is only available there, but not in
+the other project as well.
 
 Hence, the simplest solution was to go ahead and merge both projects
 into a single new project which will handle multimedia formats - be

data/doc/todo/todo_for_the_multimedia_paradise_project.md

@@ -1,111 +1,97 @@
 --------------------------------------------------------------------------------
-(1) in the sinatra-api of multimedia paradise, add
-     add video/random_simpsons
-
-also add various conversions, such as
-
-to_mp4/FILE_PATH_HERE
-^^^ this works now, but it has to be better documented, linked in
-    from the index, as well as an entry point at /to_mp4 shown.
+(1) → go through the GUIs
+  then add actions to them
+  ^^^^ and integrate all of them there, also document it.
 --------------------------------------------------------------------------------
-(2) enhance the sinatra stuff for MultimediaParadise:
-
-    In particular we need to be able to do:
+  AND ... simplify the conversion parts
+  into module Conversions
+  then .to_mp3
+       .to_momma
+--------------------------------------------------------------------------------
+(11) → in multimedia player
+      in java/
+      build a commandline player
+      a simple one.
+      somehow this breaks after a few seconds so somehow it dies
+      off...
 
+--------------------------------------------------------------------------------
+(2) → make sure that for all lib-ui-based variants we have aliases.
+      that way we can call them directly on windows via cmd.exe
+--------------------------------------------------------------------------------
+(3) → in the sinatra-api of multimedia paradise, add
+      add video/random_simpsons
+      also add various conversions, such as
+      to_mp4/FILE_PATH_HERE
+      ^^^ this works now, but it has to be better documented, linked in
+      from the index, as well as an entry point at /to_mp4 shown.
+--------------------------------------------------------------------------------
+(4) → enhance the sinatra stuff for MultimediaParadise:
+      In particular we need to be able to do:
       (a) show how many videos are available locally, in total [IMPLEMENTED]
       (b) be: able to view all registered videos files         [IMPLEMENTED]
       (c) links (also to IMDB) ^^^ done above                  [IMPLEMENTED]
-
       (d) metadata there + <- show the metadata too, codec stuff and so
-          forth via the web-interface
+      forth via the web-interface
       ALSO
       (e) be able to convert stuff ... eaudio and stuff ... hmm
-          and some overview page... what does this mean
+      and some overview page... what does this mean
       (f) play a video by embedding the video tag.
-          ok this one.^^^
-      (g) also make sure play/ works. 
-
-And document this properly in the README.gen file.
-
+      ok this one.^^^
+      (g) also make sure play/ works.
+      And document this properly in the README.gen file.
 --------------------------------------------------------------------------------
-(1) Add support for:
-
-    → Uncompressed audio formats, such as AIFF, AU or raw
-       header-less PCM
-
- esystem "ffmpeg -i file.wav -f aiff -ab 128000 -ar 44100 file.aif"
-
-to_aiff now exists but we must test it still.
-
-I tested it but we  may have to test it more thoroughly first.
-
-  → Formats with lossless compression, such as FLAC, Monkey's
-     Audio (filename extension .ape), TTA, ATRAC Advanced
-     Lossless, ALAC (filename extension .m4a), MPEG-4 SLS,
-     MPEG-4 ALS, MPEG-4 DST, Windows Media Audio Lossless
-     (WMA Lossless), and Shorten (SHN).
-  → Formats with lossy compression, such as Opus, Vorbis,
-     Musepack, AAC, ATRAC and Windows Media Audio Lossy (WMA
-     lossy).
-     Opus has what format? Opus conversion now works.
-
-  ^^^ look to get these formats back.
+(5) → Add support for:
+      → Uncompressed audio formats, such as AIFF, AU or raw
+      header-less PCM
+      esystem "ffmpeg -i file.wav -f aiff -ab 128000 -ar 44100 file.aif"
+      to_aiff now exists but we must test it still.
+      I tested it but we  may have to test it more thoroughly first.
+      → Formats with lossless compression, such as FLAC, Monkey's
+      Audio (filename extension .ape), TTA, ATRAC Advanced
+      Lossless, ALAC (filename extension .m4a), MPEG-4 SLS,
+      MPEG-4 ALS, MPEG-4 DST, Windows Media Audio Lossless
+      (WMA Lossless), and Shorten (SHN).
+      → Formats with lossy compression, such as Opus, Vorbis,
+      Musepack, AAC, ATRAC and Windows Media Audio Lossy (WMA
+      lossy).
+      Opus has what format? Opus conversion now works.
+      ^^^ look to get these formats back.
 --------------------------------------------------------------------------------
-(2) Include and connect this into the GTK stuff
-  
-    Das ganze soll langsam zu einer richtigen "MULTIMEDIA STATION"
-    werden. Und auch den GUI dazu anschaun für Verbesserungen.
-
-  Todos:
-    phed>  format conversion is one thing, but a batch 
-           wav→tagged  ogg,mp3,flac - tool would be nice
-    shevy> batch wav tagged ... tool?
-    phed>  convert a list of wav files (an album) to 
-           a fully releasable zip/zips would be fun.
+(6) → Include and connect this into the GTK stuff
+      Das ganze soll langsam zu einer richtigen "MULTIMEDIA STATION"
+      werden. Und auch den GUI dazu anschaun für Verbesserungen.
+      Todos:
+      phed>  format conversion is one thing, but a batch
+      wav→tagged  ogg,mp3,flac - tool would be nice
+      phed> convert a list of wav files (an album) to
+      a fully releasable zip/zips would be fun.
 --------------------------------------------------------------------------------
-(3) a downloader for random audio tracks. What does this even mean?
-    
+(7) → a downloader for random audio tracks. What does this even mean?
 --------------------------------------------------------------------------------
-(4) llogan> perhaps you should use the concat demuxer
-            instead of the concat protocol
-
+(8) → llogan> perhaps you should use the concat demuxer
+      instead of the concat protocol
 --------------------------------------------------------------------------------
-(7) continue with porting OLD_video.rb
+(9) → continue libui-id-tagger.
+      also  find out whether the id-tagger works on windows
+      if so or not (it does not right now), document this
+      on the README.gen of multimediaparaidse.
+      The compiling does not work. :(
 --------------------------------------------------------------------------------
-(8) continue libui-id-tagger.
-     also  find out whether the id-tagger works on windows
-     if so or not (it does not right now), document this
-     on the README.gen of multimediaparaidse.
-     The compiling does not work. :(
+(10) → all gtk3 apps should have libui counterparts.
 --------------------------------------------------------------------------------
-(9) make sure that for all lib-ui-based variants we have aliases.
-     that way we can call them directly on windows via cmd.exe
--------------------------------------------------------------------------------
-(10) all gtk3 apps should have libui counterparts.
--------------------------------------------------------------------------------
-(11) in multimedia player
-in java/
-  build a commandline player
-a simple one.
-
-somehow this breaks after a few seconds so somehow it dies
-off...
--------------------------------------------------------------------------------
-(12) Add a "play-this-video-file.cgi" and sinatra app.
-
-    The UI should be simple, start with sinatra. The view-videos
-    URL aka /view
-    should work. and
-    then add:
-
+(12) → Add a "play-this-video-file.cgi" and sinatra app.
+      The UI should be simple, start with sinatra. The view-videos
+      URL aka /view
+      should work. and
+      then add:
       play/134
-
-    ^^^ this should work as well. and allow query-based too.
-    once sinatra works, try to make it work via the .cgi page
-    but well... replace the / with _ perhaps to make ti work.
-    hmmm... yeah. well.
-    first we must add support for play/134 in sinatra.
-    Ok this works now ... we have to enable this via .cgi
-    too. This in order to complete the old functionality
-    that used to exist here at one point in time.
---------------------------------------------------------------------------------
+      ^^^ this should work as well. and allow query-based too.
+      once sinatra works, try to make it work via the .cgi page
+      but well... replace the / with _ perhaps to make ti work.
+      hmmm... yeah. well.
+      first we must add support for play/134 in sinatra.
+      Ok this works now ... we have to enable this via .cgi
+      too. This in order to complete the old functionality
+      that used to exist here at one point in time.
+--------------------------------------------------------------------------------