Windows and Linux Media Player Copyright (C) 2018, 2019, 2021, 2022 by Kevin C. O'Kane Kevin C. O'Kane
kc.okane@gmail.com
https://www.cs.uni.edu/~okane
http://threadsafebooks.com/

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Acknowledgments Runtime routines from the VLC runtime library are used for audio services. No VLC source code is used. Jan 5, 2022 Windows WSL2 The code now works with Windows 11 with WSL 2 / Ubuntu installed: First, install WSL2 on your computer. WSL2 requires Windows 11. Follow the instructions in the following to install Ubuntu: https://docs.microsoft.com/en-us/windows/wsl/tutorials/gui-apps Be sure to install nautilus, VLC and gedit as shown. The others are optional. o Be sure to have only one microphone and one set of speakers active. If there are several, the Player will randomly choose which to use. This will not produce desirable results. o Windows files are accessible from Ubuntu in WSL with references such as: /mnt/c/Users/joeuser/Desktop/filename.mp3 which references your Windows C:\ drive. You can access Windows files from the Linux environment, not the other way round. o In order to render video you must execute the following line before starting the Player: export GDK_BACKEND=x11 A good idea is to place this line at the end of the hidden file: .bashrc in your home directory. This will cause the command to be executed each time you initiate a WSL Linux session. o When you start a Linux terminal in WSL, you will be in your Linux home directory by default: /home/yourusername Files in the Windows system, for example, your Desktop will be accessible via: /mnt/c/Users/yourusername/Desktop/filename.mp3 where the letter 'c' in the above refers to your C:\ drive. Any other drives you may have will be accessible in a similar manner using their drive letters. o Placing the Player-Linux directory in your Linux home directory makes it inaccessible to the Windows system. A better idea is to place it on your Desktop (or similar Windows directory). Now its contents can be accessed directly by Windows programs. Download the Player compressed tar file from: https://www.cs.uni.edu/~okane/pocketradio.html Place the tar file (Player-Linux-x.xx.tgz) on your Desktop where "x.xx" are current release numbers. o Open a Linux terminal session and change directory to your Desktop: cd /mnt/c/Users/yourusername/Desktop/ o Decompress the file with the command: tar xvzpf Player-Linux-x.xx.tgz This will create the Player-Linux directory. o From the Linux terminal session, enter the Player-Linux directory and, as root, run: ./GeneralInstall.script (you can become root by typing sudo su). The above installs any software you may need. An internet connectioon is required. The above can take several minutes to run. When done, exit root (type exit or control-d). o From the Linux terminal session, compile the Player: make -B The "-B" option forces all files to be compiled. The Player can now be run with the command ./Player-bin Note: The prefix "./" is normally required to run a program from the current directory. You can eliminate the need to type "./" each time by adding the line: PATH=$PATH:"." at the end of your .bashrc file (located in your Linux home directory).. o You need to populate the file program.lst with the addresses of media files. First, from the Linux terminal session, run gedit on program.lst in the Player-Linux directory: gedit program.lst & There may be lines in this file. They are probably files from my computer. You need to erase them all by selecting all (control-a) forllowed by (DEL or contyrol-x). Note the "&" at the end of the line. This permits gedit to run as a separate process and control is returned to your Linux terminal session. If you omit it, your terminal session will wait for gedit to finish before it processes any additional commands. o Next open nautilus which is the file explorer for Ubuntu: nautilus & Navigate via the "File System" (on the left) to your directory containing media files. This directory may be on your C:\ or another drive. Select one or more of these files, copy them (control-c) and, in the gedit window, paste them (control-v). Save the results in the gedit window, rinse and repeat as needed. When you are finished, save and exit gedit. You may add additional files at any time. Be certain to only include file names that refer to common media file types and be certain there are no blank lines in program.lst Nautilus will interpret your file names in the format Linux expects to see. Thus, a file in your Windows system whose Windows reference is something like: C:\Users\username\Music\country\orange blossum special.mp3 will be copied to gedit as: /mnt/c/Users/username/Music/country/orange blossum special.mp3 This is the format the Player expects to see. You must use nautilus and gedit for this. Notepad and Windows Explorer will not produce usable results. The next time you start Player-bin, you should see the media files and they should be playable. o In order to begin your session at the Desktop level, you may want to add the line: cd /mnt/c/Users/yourusername/Desktop/ at the end of the .bashrc file. This will place you in your Desktop when you start your terminal. You can return to your home directory at any time by typing, with no arguments: cd ------------------------ Overview Linux install Overview This app was developed using Xorg and Gnome on Linux Mint with Mate. It should work with any similar system. It has been tested on current versions of the following Debian related distros subject to the notes stated. Ubuntu (with Wayland disabled) Ubuntu 21.04 uses Wayland by default. Wayland breaks many Xorg apps including this one. If you want to use the player with Ubuntu 21.04, you need, as root, to modify the file: /etc/gdm3/custom.conf and uncomment (remove #) from the line: #WaylandEnable=false and re-boot. The issue involves libvlc video embedding. This feature is not currently supported in Wayland by VLC. A version of the player without video embedding will be posted. If you are using Nvidia drivers, as of this writing, they are not compatible with Wayland and your system may already be in Xorg mode. You can determine if your system is running Wayland with the bash command: echo $XDG_SESSION_TYPE The Player checks for "x11" in XDG_SESSION_TYPE and disables the Video checkbox in settings if not found. You may re-enable videos by checking the box but you must do this prior to playing any media file. If "x11" really not present, the video will be randomly placed on the screen. Linux Mint LMDE No problems. Linux Mint Cinnamon No problems. Linux Mint Mate No problems. Linux Mint Xfce Use cut/paste to add file references to the Edit panel (rather than drag/drop). MX Linux Change GTK3 Theme from Breeze to Default. The MX default GTK3 theme is called 'Breeze'. This theme generates errors when used with the Player and WegKit. These result in misalignment of widgets on the screen. To compensate, change the setting from Breeze to Default. To do so, go to: Settings System Settings Application Style Gnome Application Style (GTK) and change 'Select GTK3 Theme' from Breeze to Default. This error appears to be a Breeze issue and may be fixed in future releases. Attempts to create a workaround will also be tried in future releases of SGR Player. Debian (with Wayland disabled) See notes above for Ubuntu. As above, Wayland needs to be disabled. Edit the file: /etc/gdm3/daemon.conf and uncomment (remove #) from the line: #WaylandEnable=false The Player checks for "x11" in XDG_SESSION_TYPE and disables the Video checkbox in settings if not found. You may re-enable videos by checking the box but you must do this prior to playing any media file. If "x11" really not present, the video will be randomly placed on the screen. Both the Linux and Windows source code are contained in a single distribution however the Windows, libraries, which are quite large, are in a separate distribution. The Windows distro contains the following additional libraries and files: assets (directory) etc (directory) installed (directory) library (directory) share (directory) Player.lib Player.obj Player.exe Player.exp The Linux main module is Program.c and the Windows main module is Player.cpp. To compile and run in Linux: GeneralInstall.script (one time only) make -B ./Player-bin To compile and run in Windows: compile.bat sgr.bat File names used in the Linux version should be of the form: /dir1/dir2/file.mp3 File names used in the Windows version should be of the form: C:\dir1\dir2\file.mp3 Code specific to Windows is in 'sgr-code/windows'. Code specific to Linux is in 'sgr-code/linux'. Code common to both is in 'sgr-code/common' Any changes made to the Glade file in the Widows version must be processed by glib-compile-resource in order to update the 'resource.c' file. A script, 'ResourceCompile.script' is provided that will create 'resource.c' but this requires a Linux platform to run. The graphics code is based on GTK 3 (3.24 at this point in time). Recently, GTK 4 was released. As GTK 4 is still unstable and not yet widely accepted on Linux, the Player continues to use GTK 3 which is currently under long term support. If and when GTK 4 becomes stable and widely used, the Linux distro will migrate to GTK 4. Given past experience with GTK developement, this may be some time in the distant future. --- Detailed Linux Instructions Software This system has been developed for Ubuntu/Mint compatible versions of Linux. Manual modification of the system library code may be required for use on some other (non-apt based) Linux distros at this time There is a Makefile for this system. To compile, type: make -B to force full compilation of all modules: If this is the first time you have installed the Player, use the exeutable bash script file GeneralInstall.script in order to install any needed software before attempting to compile or use it. Note: this script files makes use of apt-get to install software. This may nopt work on all systems. The WebKitGtk package is now required. The apt-get command for this is at the end of GeneralInstall.script. If you have previously installed the software, you will need to manually install WebKitGtk. Although a binary executable is included, you probably should use 'make' to compile your own version of the code. The program has been developed using 'out-of-the-box' default Linux desktop themes. The slide show is programed via a file named slides.lst which should contain a collection of full path descriptions to target JPG and PNG files. An example is provided (it will not work on your system as it uses path names valid only the author's machine). Gnome Desktop Themes Different Gnome desktop themes may cause the Player to render graphic objects differently. Some of these may not be nice to look at. You may need to try different desktop themes Most of the icons used by the Player are standard system icon types. The appearance of these is a system icon setting. Many desktops permit the user to select the icon package to be used. Depending on which package you select, the icons will appear differently. Adjust your system desktop settings as needed. Generally, the base Gnome set of icons look best. The preferred distro is Linux Mint Mate using the Mint-X theme with Gnome icons. Other themes work but some better than others. You may need to experiment. Help Most objects on the screen have a tool tip explanation. Tool tips are off by default but you can turn them on in the 'Settings' panel. Configuration Files The following files must be placed in the directory from which Player-bin is executed. program.lst This is a text file containing absolute file addresses of playable media files (MP3, MP4, FLAC, etc). File names must be relative to root. Example: /home/myhome/music/tune.mp3 Files referenced in the manner above will be played by embedded VLC libraries. If a file so referenced has a recognized video format, a small panel will open showing the video. Files referenced as above will have green tiles (or red if they have been played.) If a reference is of the form: Files referenced as above will have green tiles (or red if they have been played.) If a reference is of the form: file:///home/user_name/music/sometune.mp4 or https://www.youtube.com/watch?v=GN75XDDm_DI it will be played thru the internal web browser. Files played thru the web browser must be individually selected for play (i.e., they will not operate in program mode as the web browser does not signal end of play). The tiles for files similar to the above will be dark blue. If a line in program.lst begins and ends with a forward-slash (/), the line is assumed to point to a directory. The files from the directory will be loaded. If a line does not being with a forward-slash but ends with a forward-slash, a visual tile with the contents of the line will be inserted. This tile will not play but can be used as a marker. It will appear with the text in a light blue tile. The contents of the text may be searched for by the Program Search box. Marker tiles disappear if the program is sorted or randomized. album.lst A text file containing absolute addresses of directories containing media files. Each directory must contain a playlist file named playlist.m3u, which will be used to determine the order of play if the album is loaded. If the directory contains a file named cover.jpg or cover.png, the image will be loaded into the slide panel when a file from the directory is played and you have enabled covers to be displayed. Albums may be loaded into the program list by right or left clicking on the tile in the Albums panel. A left click loads the album at the end of the program while a right click loads the album at the beginning of the program See below for further details on albums. Loading an album causes all entries to be marked as playable. The file playlist.m3u must be present in the directory. Files will be loaded in the order in which they appear in 'playlist.m3u'. Lines in playlist.m3u are either full directory names of playable audio files if they are not local to the directory. If they are local to the directory of the playlist.m3u file, thay are just file names with no directory information. Blanks are permitted. Comments beginning with # are permited in playlist.m3u. Not other format is recognized. title.txt The first line of text in this file will appear at the player title in the upper left corner of the player. You may replace it with your own subject to a length restriction of about 27 characters. The text will be automatically centered. Trailing or leading blanks are counted for purposes of centering. When you start the Player, the initial tiles on the screen are populated from the contents of program.lst, if any. If there is no program.lst, all tiles will be blank initially. You may build a program.lst by opening albums. You may build program.lst file by opening the GUI text editor and then copying and pasting files from an explorer window into the text editor window. These must be full system path references to the media file. Command Line Options Note: the CLI parser at this time is not fault tollerant. Type it right of it won't work. There must be only ONE space between the parameter name and its argument.

--background-color color The background color. The color string can either one of a large set of standard names (such as red, blue, gray, etc.), or it can be a hexadecimal value in the form #rgb #rrggbb, #rrrgggbbb or #rrrrggggbbbb where r, g and b the are hex digits of the red, green, and blue components of the color, respectively. Note: color numbers MUST be in quotes. No exceptions. The default is '#111122'.

--microphone-max number The value that represents full microphone gain on your system in percent. Default: 100% --music-home-directory dir Full directory path to root of music directory containing your music files and sub-directories containing music files. The default is $HOME/Desktop/Broadcast where $HOME is your home directory (such as /home/userid). The Player will determine the value of $HOME form envirnment variables. Example: --music-home-directory /media/username/diskName/myMusic --program-max nbr Maximum number of program entries. Default: 4096 --code-home dir Full Directory path to code (usually not needed) as the program will determine this at run time. Example: --code-home /home/username/Desktop/Player --program-list file-path Full directory path and file name of program.lst if not in code-home (default) Example: --program-list-dir /home/username/Desktop/Player/program.lst --album-list file-path Full directory path and file name of album.lst if not in code-home (default) Example: --album-list-dir /home/username/Desktop/Player/album.lst --timer-res number Number of milliseconds between updates to the audio graphs and meters (delault: 100). Use a higher number on really old machines with slow graphics. --max-agc number Maximum gain allowed by AGC. Default: 120. This may also be set in the Settings panel. --rand-cover-time Time in seconds between random cover art. Default: 15. This may also be set in the settings panel. Detailed Windows Instructions The Windows implementation is similar to the Linux version with the exceptions that (1) some features are unavailable, and (2) new development is suspended until due to the removal of GTK 3 and related packages from VCPKG. If you use the provided binary, you may need to authorize the executable (Player.exe) to run (right-click on it in an explorer window and, under Properties | Security, authorize execution. Do NOT use Player.exe directly as it requires libraries & linkages which sgr.bat provides. Use sgr.bat to run the Player. WAIT WAIT WAIT WAIT During the first second or two, the system connects to Windows Audio. During this time you may NOT click on any buttons or scroll bars. If you do, the program, may crash. Help Most objects on the screen have a tool tip explanation. Tool tips are off by default but you can turn them on in the 'Settings' panel. Scan Media & Media Time Calculations The tiles in the upper tray will contain duration, start and end times. The times are calculated only for the first 12 playable tiles. You can get metadata (including time) for any tile by right-clicking on it. In the 'Settings' panel, you can cause the player to extract the time for all media files in the playlist by clicking the 'Scan Media' button. Scanning can take a while but it will improve the speed of rearranging the files (drag/drop and randomization). If you scan the media, the times of all tiles will be shown. Software If you wish to compile this, you need to get Microsoft Visual C++ and the Microsoft Windows SDK. Other libraries are included in the distro (see below). These include legacy copies of GTK 3 and related software which are no longer in VCPKG. Use 'compile.bat' to compile the system. Notes: Configuration Files The following files are to be placed in the directory from which Player-bin is executed. program.lst A text file containing absolute file addresses of playable media files (MP3, MP4, FLAC, etc). File names must be relative to root. Example: C:\Users\joeUser\Music\RockMusic1\mp3\AL STEWART - Time Passages.mp3 or "C:\Users\joeUser\Music\RockMusic1\mp3\AL STEWART - Time Passages.mp3" Copies of some of my program.lst files (*.lst) are included by way of example. The will not work on your system. You need to replace them. title.txt The first line of text in this file will appear at the player title in the upper left corner of the player. You may replace it with your own subject to a length restriction of about 27 characters. The text will be automatically centered. Trailing or leading blanks are counted for purposes of centering. slides.lst A list of slides to be displayed. These should be the full path descriptions to .jpg, and .png files. Entries will be of the form: C:\Users\joeUser\mySlides\abc.jpg or "C:\Users\joeUser\mySlides\abc.jpg" When you start the Player, the initial tiles on the screen are populated from the contents of 'program.lst', if any. If there is no program.lst, all tiles will be blank initially. You may load/save the contents of program.lst or load/save files with similar contents but other names. Albums have been enabled. See the example files (album.lst and the directory SGR Albums). Album.lst contaings lines that point to directories. In these directories are (1) a playlist in playlist.m3u format and (2) optionally, cover.jpg or cover.png. When an album's tile is clickes in the Albums panel, the contents of the playlist.m3u are added to the player's plalist. Examples of these files are provided. Since they use directoriy paths and file names on my computer, they will not work on yours. Replace them with similar files tailored to your configuration. Issues MP3 Cutoff MP3 files where the sound continues to the very end of the file may render with a fraction of a second of the final sounds not audible. This appears to be a libVlc frame buffering issue with compressed files. Delay of First Play When you play the first file there may be a delay. This is due to libVlc initialization and no workaround has been found to date. This only occurs on the very first file played. Subsequent files will play normally. Special Characters in File Names The Windows file system API being used (which were ported from Linux) does not accept files names with non-ASCII characters at this time. These file names will be rejected. Note: this does not happen on Linux. Tooltips Turning off tooltips in the Settings panel does not disable all tooltips. This is a Windows issue. Compressor The compressor settings do not work at present pending VideoLan API availability. Random Error Messages Some software (e.g., libVlc) throw error messages. These are generally not real errors and can be safely ignored. The Player itself will generate messages indicating its actions and, possibly, error conditions. Glade Note: the Windows resource file is named WinResource.xml. It results in the file winresource.c when compiled. The Glade file for Windows is named WinPlayer.glade. Audio Meters There are two audio meter displays. One shows two traditional VU meters, one for left and one for right. The other shows digital animations of the left, and right channels along with a meter that shows which (left or right) is louder and, finally, a meter labelled 'microphone'. At present, the microphone meter is not functional in the Windows version. It is functional in the Linux version. No Decorations The 'Hide Decorations' checkbox removes the title bar. When the title bar is not present, you cannot drag or resize the window. This option is included because OBS includes the title bar of the Player in it's window grab. If the title bar is not present, the Player will fit in a standard wide screen OBS window without adjustment. Be sure to drag your window to a convenient location on the screen before removing the decoration. If you uncheck the box, the decoration (title bar) will re-appear. Tiles You may drag media tiles to change their order. To move a tile from a different page, hold down the control key and left-click on the tile to be moved. To place the tile, again, holding down the control key, left-click on the tile prior to which you want to place the moved tile. Your Message in Lights If your Player directory contains a file named "title.txt" containing one or more lines. The text of the first line will be rendered as the title of the Player. You may adjust the font for this in css/gtk.css under the #logo entry. If you change the line while the player is running, the title in the player will update within firve seconds. Edit Panel Entries in the Edit panel may be cut, pasted or deleted. A file can be scheduled for re-play by checking its Play box. If you copy/paste and entry for your file system, be SURE you copy-path and not copy file. Copying the file will not work. If you want to copy/paste a file into the program list, right click of the file while holding down the right Shift key. This will allow you to see the 'copy path' option. You may copy/paste a single file into any of the Edit panel entry boxes. If you highlight and copy/paste multiple files you may paste only into the lower 12 entry boxes. The top entry box, is used to display individual files only. Drag and drop from media files to the Player is not permitted in the Windows version. Full directory searches may be conducted and the results added to the program rows (the program list). Tile Repositioning When not in program mode, if you click on a tile in the upper tray of tiles, the tile will reposition and be displayed on the first position in the program (may involve tile page change) and begin playing. On a page in the upper tray, you may drag tiles by holding down the left mouse button and dragging the tile to the position prior to which you want it placed. If in a page in the upper tray other than the first page, if you hold down the left button and right clicking on the tile prior to which you want the previously selected tile to be placed. In program or automation mode, if you click on a tile, the tile will reposition as above and queue to be played. If you click on a tile in the lower tray, it will be moved to the first position in the upper tray. If in program mode, it will be queued to play next. Audio Panel The audio panel should be self explanatory except that the compressor options do not work at present pending an update from VLC on the compressor API. Audio settings are not valid until a media file has been played and an internal equalizer created. Video Media If a media file is recognized as containing video, a small video window will be opened containing the video. The title of this window will always be "SGR Video Preview" for purposes of OBS linkage. The video window will disappear when the media file is no longer playing. The X box on the video preview is inactive. Click the Halt button to end a video (or any other media). Tooltips All on screen objects have extensive tooltips that will popup if you hover over them. Alternatively, you can turn tooltips off with the crossout 'Tooltips?' button. Command Line Options: Note: the CLI parser at this time is not fault tolerant. Type it right of it won't work. There needs to be only ONE space between the parameter name and its argument. --background-color color The background color. The color string can either one of a large set of standard names (such as red, blue, gray, etc.), or it can be a hexadecimal value in the form “#rgb” “#rrggbb”, “#rrrgggbbb” or “#rrrrggggbbbb” where “r”, “g” and “b” are hex digits of the red, green, and blue components of the color, respectively. Note: color numbers MUST be in quotes. No exceptions. --max-agc number Maximum gain allowed by AGC. Default: 125. --rand-cover-time Time in seconds between random cover art. Default: 10. This may be adjusted at run-time (in Settings). Program Search The Program Search entry box in the Tiles panel will search for entries in the current program list. It will attempt to match as many characters as you type. Regular expressions are not supported. The 'Repeat' button repeats the search looking for the next instance of the characters, if any. The search is case insensitive. If a tile is found, the lower set of tiles will be repositions so that the tile found if listed first. Clicking it will cause it to be moved to the beginning of the program list. Album marker tile names may be the subject of a search. Volume Levels and Automatic Gain Control In addition to the preAmp slider, there are two checkboxes named AGC1 and AGC2. Checking AGC1 turns on the Automatic Gain Control. The system will, once a second, adjust the volume level of the playing file. Initially, the volume level will be incremented. When a peak is detected. The volume will retreat. Further peaking will cause the volume to be further lowered. Once a peak has been detected, the volume will not automatically increase for the duration of the media file. Checking AGC2, if AGC1 is checked, allows the volume to increase after a peak has been detected. With AGC1, after a peak is detected, only decreases will occur for the current media file. To avoid gain issues, you may want to try Audacity's sound normalization effect. You can apply normalization to all your files by using the 'Chains' option. This cleverly hidden but quite easy to use option allows you to apply one or more effects to any number of media files. It is located under Files | Chains.