SGR-PLAYER

Copyright (C) 2018 - 2025 by Kevin C. O'Kane

Kevin C. O'Kane 
kc.okane@gmail.com
https://www.cs.uni.edu/~okane 
http://threadsafebooks.com/

December 6, 2025
------------------------------------------------------------------------------

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.

Formatting

astyle --style=banner --indent=tab 
astyle -A6 --indent=tab file.c

------------------------------------------------------------------------------

Build It Yourself

- Run DebInstall.script as root. It will download from standard repositories 
  and missing libraries. These are needed to compile and run the app.

- run: 
       ./configure && make -B -j X 

  where X is the number of CPU cores your machine has. You will be asked for
  the root passsword in order to build tan installer.

- run 
        sudo dpkg --install sgr-player-amd64.deb

- alternatively, from an explorer window, double click on sgr-player-amd64.deb and
  this will run the installer just built.

Using a Pre-Built Installer

The distro comes with Linux Mint and Ubuntu installers. These are for the
versions of Mint and Ubuntu noted in their names. To run these use:

        sudo dpkg --install sgr-player-amd64-<VERSION>.deb

Alternatively, if your system supports it, double click on the correct
installer from an explorer window.

If not all libraries are present or downloaded, run:

        sudo apt install -f

which should get the missing libraries. If this faile, run the DebInstall.script
noted above and repeat,

To Run sgr-player

- From a command line type sgr-player

When you run sgr-player for the first time, the fiollowing directories will be 
created:

	/home/YOU/sgr-player
	/home/YOU/sgr-player/media

File program.lst - a list of the files to appear in the entry boxes in the player -
will be placed in the first of these.

Media files placed in the second can be scanned and loaded into program.lst.

Notes:

The VLC and GTK libraries enjoy dumping random messages into the output. These are usually
meaningless and you should ignore them.

The graphics code is based on GTK 3 (3.24 at this point in time).

Recently, GTK 4 was released.  

As GTK 4 breaks GTK 3, the sgr-player wil continue to use GTK 3 which is 
currently under long term support and will be for many years to come. 

While most GTK functions are the same in both GTK3 and GTK4, many have spelling 
and parameter changes and some features are missing.

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.
In fact, GTK4 may never be widely accepted.

Some drag and drop functions are not available in Ubuntu and Xfce due to difference 
in their windows managers.

---

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 /home/YOU/sgr-player.

	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.

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.

Files may be dragged to the entry boxes in most desktops (but not Ubuntu and 
Xfce, for example).


album.lst

A text file containing absolute addresses of directories containing media
files. It should be placed in /home/YOU/sgr-player.

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.

slides.lst

A list of absolute file addresses of slides that may be played by the
player. Slides are of .png, .jpg and other static image types. The file
is placed in /home/YOU/sgr-player.

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.
<p>

--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'. 

--program-max nbr		

Maximum number of program entries. Default: 4096

--microphone-max number		

The value that represents full microphone gain on your 
system in percent. Default: 100%

--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.


Compressor

The compressor settings do not work at present pending VideoLan API availability.

