SGR-PLAYER

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

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

August 1, 2026
------------------------------------------------------------------------------

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.

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

Build It Yourself

- Run DebInstall.script as root. It will download from standard repositories 
  any missing libraries needed to compile and run the app. See notes below
  on VLC libraries if you are compiling on Widows with WSL2. You will need
  additiona VLC libraries not covered by DebInstall.script

- 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 pre-built installer should only be used on Linux systems with Linux file 
systems. WSL versions of Linux are different. 

The distro comes with a Linux Mint installer. This is for the current version
of Mint which is 22.3 as of this writing. 

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

To Run sgr-player

- From a command line type sgr-player

When you run sgr-player for the first time, the following working directories 
will be created if needed:

	sgr-player
	sgr-player/media
	sgr-player/slides
	sgr-player/Albums

These will be created in $HOME/sgr-player by default.

If you wish sgr-player to be placed somewere else, before starting sgr-player,
type the following to a terminal:

	PLAYER=/some/where/else
	export PLAYER

The sgr-player directory and its descendants will be placed in /some/where/else
if you have permissions to access that location.

NOTE: if you place sgr-player in a location other than your home directory (the
default) you will need to set and export the PLAYER environment variable at least
for each terminal session.

Populate the subdirectories as follows:

  media   video and audio media files to be played

  slides  still images of type .png or .jpg to be displayed as a slide show

  Albums  directories whose names will appear on tiles containimg a file
          named playlist.m3u wich itself contains a list of media files and
          locations according to the m3u file format. The dirctory should also
          a file named cover.jpg which will be shown in the tile for this
          album.
         
----------------------------------------

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

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

- Most objects on the screen have a tool tip explanation. 

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

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

Windows 11 WSL Ubuntu Linux

The code works with Ubuntu 24.04 LTS and probably others. You will need to
run the DebInstall.script as well as all system ordinary Ubuntu updates.

If you place the sgr-zippy on a Windows file system outside the ordinary
WSL Linux tree, you will need to configure your WSL Ubuntu to allow for
Linux style file and directory permissions.

That is, normally you will install the sgr-zippy directory in your /home/you/
directory and compile and run it from there.

However, you may also install and compile it into a directory in the larger
Windows environment.

If you use th3e WSL Linux file system, you may ignore the following.

Windows disks and file systems are accessible to Ubuntiu in for form:

        /mnt/c
        /mnt/c/Users/you
        /mnt/d
	...

Where the first is your C:\ drive; the second is the path to your Windows home
directory (where 'you' is your Windows ccount name); and the third accesses
your D:\ drive.

If you place sgr-zippy on these or similar drives, you need to modify an Ubuntu
configuration file.

Change the file: /etc/wsl.conf to the following:

[boot]
systemd=true

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

You need to be root to do this. Reboot (wait at least 15 seconds before
restarting).

Virtual Box Linux on Windows

If you run Linux with Oracle Virtual Box on Windows AND you store the
distro on a vboxsf firectory (i.e., an NTFS file system), the configure
program will insert the option

        --nocheck

into the dpkg-deb command line in Makefile. This option stops certain dpkg
checking that would flag as errors vbox NTFS files wich have limited file
protection bit capabilities. NTFS lacks the full set of file permissions
permitted in Linux. Hwence the need for --nocheck

The reason why you might want to install the distro on an NTFS file system
is to make in concurrently available to both WSL Ubuntu and VBOX Linux. This
is not advised unless you have detailed familiarity with WSL and Vbox.

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

VLC 4 and WSL

The current sistro of the VLC libraries is version 3. Unfortunately, there
are audio timeing comflicts between VLC 3 and WSL2. These produsce noise and
dropouts.

Version 4 of VLC may solve some of the audio problems. VLC 4 is still under
developement and may contain instabilities.

For those who want to risk its possible instability issues, you can install 
it with the following command line code:

sudo add-apt-repository ppa:videolan/master-daily
sudo apt update
sudo apt install vlc

Note: there is a script file in the distro that does this.

This will install version 4. Version 3 will still be available.

WSL Casting With OBS

Turn the Windows microphone setting to zero (0) to avoid feedback. 
Otherwise, the mic will be passed to WSL and then back to Windows
to mix with the OBS mic capture. Not nice. 
