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.