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

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

Installation

Using a Pre-Built Installer

Be sure you run DebInstall.script once before attempting to use an installer.
This script installs system libraries needed by the program. From the distro
directory:

	sudo ./DebInstall.script

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

If you are installing on WSL, you will need a WSL version of the installer.
This will probably require building the program as shown below. 

To install from a .deb file:

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

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

Building the Installatio 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

	sudo ./DebInstall.script

  The DebInstall.script need only be run once. For WSL installations, the 
  newer version (4) of VLC should be installed. See below for instructions.
  VLC 4 is not needed for Linux versions.


- run: 
       ./configure

- run 

	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

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

To Run sgr-player

- From a command line type 

	sgr-player

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

Directories

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

	$HOME/sgr-player
	$HOME/sgr-player/media
	$HOME/sgr-player/slides
	$HOME/sgr-player/Albums
	$HOME/sgr-player/web

If you wish sgr-player to be placed somewhere 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. Otherwise, the Player will default to $HOME/sgr-player

Populate the sgr-player 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.

When you run sgr-player, the files in sgr-player/media will display in the edit
and tiles windows and may be played by clicking on their 'play' button or
in sequence by clicking on the 'Play Pgm' button.

Entries in the Album directory are named directories. The name of the directory
will appear as an album tile. The contentes of each directory are:

	playlist.m3u
	cover.jpg

The playlist.m3u file contains full path descerioptions to media files. These 
files constitute the album. The file cover.jpg contains an image that will appear 
in the tile.

If you click on a valid Album tile, the files referenced in its playlist.m3u
will be loaded (added) into the edit widow at the end. You may want to clear the
edit window first by clicking the 'Clear Pgm' button.

Slides will be randomly displayed in the slides window if you tuurn on the
slide show option in the player.
         
------------------------------------------------------------------------------

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). There are
  no plans to convert to (incompatible) GTK4.

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

- Most objects on the screen have a tool tip explanation which describes their
  function.

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

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

Windows 11 WSL2 Ubuntu Linux

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

Windows disks and file systems are accessible to Ubuntiu in the 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 have one. There are file name differences between
Windows and Linux so not all files are accessble.

To improve file system interoperability, 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).

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

VLC 4 and WSL

The current distro 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.

You can install VLC4 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.

Version 3 will still be available.

The microphone meter is not displayed in WSL versions of the program due
to problems involving feedback in the WSL audio system.

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

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. 

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

The --nocheck option in Makefile.in is a workaround forr file protection limitations
in NTFS files. 


