expanded and cleared up documentation / annotation (adafruit#139)

.gitignore

@@ -54,3 +54,4 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
+.DS_Store

Adafruit_Video_Looper/video_looper.py

@@ -269,8 +269,8 @@ def _animate_countdown(self, playlist):
         """Print text with the number of loaded movies and a quick countdown
         message if the on screen display is enabled.
         """
-        # Print message to console with number of movies in playlist.
-        message = 'Found {0} movie{1}.'.format(playlist.length(), 
+        # Print message to console with number of media files in playlist.
+        message = 'Found {0} media file{1}.'.format(playlist.length(), 
             's' if playlist.length() >= 2 else '')
         self._print(message)
         # Do nothing else if the OSD is turned off.

README.md

@@ -1,21 +1,21 @@
 # pi_video_looper
 An application to turn your Raspberry Pi into a dedicated looping video playback device.
-Can be used in art installations, fairs, theatre, events, infoscreens, advertisment etc...
+Can be used in art installations, fairs, theatre, events, infoscreens, advertisements etc...
 
-Easy to use out of the box but also has a lot of settings to make it fit your use case.
+Works right out of the box, but also has a lot of customisation options to make it fit your use case. See the [video_looper.ini](https://github.com/adafruit/pi_video_looper/blob/master/assets/video_looper.ini) configuration file for an overview of options. 
 
-If you miss a feature just post an issue on github. (https://github.com/adafruit/pi_video_looper)
+If you miss a feature just post an issue on Github. (https://github.com/adafruit/pi_video_looper)
 
-Currently only Raspberry Pi OS Lite __(Legacy)__ is supported.
-You can download it from here: https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy
+Currently only the __Legacy__ version of Raspberry Pi OS Lite is supported.
+You can download it from here: <https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy>
 
-There are also pre-compiled versions available from: https://videolooper.de/ (but they might not contain the latest version of pi_video_looper)
+There are also pre-compiled versions available from <https://videolooper.de> (but they might not always contain the latest version of pi_video_looper)
 
 ## Changelog
 #### new in v1.0.10
  - NEW PLAYER: "Image Player" (beta)  
-   The new player can display images instead of videos (slideshow).  
-   Display duration and other options can be controlled via "image_player" section in ini  
+   Displays images in a slideshow instead of playing videos.
+   Display duration and other options can be controlled via the "image_player" section in video_looper.ini  
    All other settings, like background image, color, wait time, copy mode, keyboard shortcuts, etc. should work as expected  
    Currently tested formats: jpg, gif, png (others might work also - you need to adapt the extensions setting)
 
@@ -34,10 +34,10 @@ There are also pre-compiled versions available from: https://videolooper.de/ (bu
 
 #### new in v1.0.6
 
- - Support for OMXPlayer ALSA sound output.  
-   Enabled by setting `omxplayer.sound` to `alsa`. A new config key `alsa.hw_device` can be used to specify a non-default output device.
+ - Support for omxplayer ALSA sound output.  
+   Enabled by setting sound output for omxplayer to `alsa` in video_looper.ini. A new config key `alsa.hw_device` can be used to specify a non-default output device.
  - Support for ALSA hardware volume control.  
-   The new config keys `alsa.hw_vol_file` and `alsa.hw_vol_control` can be used to set the output device volume based on a text file provided with the videos.
+   The new config keys `alsa.hw_vol_file` and `alsa.hw_vol_control` can be used to set the output device volume in a text file provided with the videos.
  - The `sound_vol_file` functionality can now be disabled by leaving the config value empty.
 
 #### new in v1.0.5
@@ -47,13 +47,13 @@ There are also pre-compiled versions available from: https://videolooper.de/ (bu
    Paths in the playlist can be absolute, or relative to the playlist's path.  
    Playlists can include a title for each item (`#EXTINF` directive); see next point.
    If something goes wrong with the playlist (file not found etc.) it will fall back to just play all files in the `file_reader` directory. (enable `console_output` for more info)
- - Support for video titles (OMXPlayer only).  
+ - Support for video titles (omxplayer only).  
    Can display a text on top of the videos.  
    To be enabled by config key `omxplayer.show_titles`.
    Without a playlist file, titles are simply the videos' filename (without extension).  
-   If a M3U playlist is used, then titles come from the playlist instead.
+   If an M3U playlist is used, then titles come from the playlist instead.
 
-   An easy way to create M3U files is e.g. VLC. For an example m3u file see assets/example.m3u
+   An easy way to create M3U files is e.g. VLC. For an example M3U file see assets/example.m3u
 
 #### new in v1.0.4
  - new keyboard shortcut "k"  
@@ -76,7 +76,7 @@ There are also pre-compiled versions available from: https://videolooper.de/ (bu
 
 #### new in v1.0.2:
  - in directory mode the directory is now monitored;
-   if the number of files changes the playlist is regenerated (usefull if the folder is filled e.g. via a network share)
+   if the number of files changes the playlist is regenerated (useful if the folder is filled e.g. via a network share)
  - some defaults have changed
  - new option for the countdown time (default is now 5 seconds)
  - new option for a wait time between videos (default is 0 seconds) 
@@ -87,17 +87,23 @@ There are also pre-compiled versions available from: https://videolooper.de/ (bu
 
 #### new in v1.0.1:
  - reworked for python3
- - keyboard control (quiting the player)
+ - keyboard control (quitting the player)
  - option for displaying an image instead of a blank screen between videos
 
-#### how to install:
-sudo ./install.sh
+## How to install
+`sudo apt-get install git`  
+`git clone https://github.com/adafruit/pi_video_looper`  
+`cd pi_video_looper`  
+`sudo ./install.sh`
 
-#### features and settings
-To change the settings of the video looper (e.g. random playback) edit the `/boot/video_looper.ini` file via ssh with `sudo nano /boot/video_looper.ini` or directly on the RPis SD Card via a cardreader.
+Default player is omxplayer. Use the `no_hello_video` flag to install without the hello_video player (a lot faster to install):  
+`sudo ./install.sh no_hello_video`
+
+## Features and settings
+To change the settings of the video looper (e.g. random playback, copy mode, advanced features) edit the `/boot/video_looper.ini` file, i.e. by quitting the player with 'ESC' and logging in to the Raspberry with an attached keyboard, or remotely via ssh. Then edit the configuration file with `sudo nano /boot/video_looper.ini`. Alternatively insert the SD card into your computer and edit it with your preferred text editor.
 
 #### copymode explained:
-when a usb drive with video files is plugged in, they are copied onto the rpi. (with progress bar)
+when a USB drive with video files is plugged in, they are copied onto the rpi. (with progress bar)
 
 to protect the player from unauthorised drives a file must be present on the drive that has a filename 
 as defined in the password setting in the ini file (default: videopi)
@@ -113,8 +119,8 @@ Note: files with the same name always get overwritten
     * with hello_video there is no gap when a video is repeated but there is a small gap between different videos
     * with omxplayer there will also be a short gap between the repeats
 
-* if you have only one video then omxplayer can also loop seamlessly (and wth audio)
-* the last supported Rasperry Pi OS image version is 2021-05-07 (https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2021-05-28/2021-05-07-raspios-buster-armhf-lite.zip)
+* if you have only one video then omxplayer will also loop seamlessly (and with audio)
+* the last supported Rasperry Pi OS image version is [2021-05-07-raspios-buster-armhf-lite.zip](https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2021-05-28/2021-05-07-raspios-buster-armhf-lite.zip)
 
 #### keyboard commands:
 if enabled (via config file) the following keyboard commands are active:

assets/video_looper.ini

@@ -1,76 +1,82 @@
-# Main configuration file for video looper.
-# You can change settings like what video player is used or where to search for
-# movie files.  Lines that begin with # are comments that will be ignored.
-# Uncomment a line by removing its preceding # character.
-
-# Video looper configuration block follows.
+# video_looper.ini
+# Main configuration file for video_looper.
+# The video_looper works right out of the box by playing any video files that
+# are in the root directory of an attached USB drive.
+# In this file you can change a lot of the video_looper's behavior, like what
+# video player is used or where it looks for media files.  
+# Lines that begin with # are comments that will be ignored.
+# Uncomment (=activate) a line by removing its preceding # character.
+# Use ./reload.sh to restart the video_looper with any changed settings.
+
+# Video_looper configuration block follows.
 [video_looper]
 
-# set which video player will be used to play movies.  Can be either omxplayer or
-# hello_video.  omxplayer can play common formats like avi, mov, mp4, etc. and
+# Set which video player will be used to play media files.  Can be either omxplayer,
+# hello_video or image_player. omxplayer can play common formats like avi, mov, mp4, etc. and
 # with full audio and video, but it has a small ~100ms delay between videos.
-# if there is only one video omxplayer can also loop seamlessly
+# If there is only one video omxplayer can also loop seamlessly.
 # hello_video is a simpler player that doesn't do audio and only plays raw H264
 # streams, but loops videos seamlessly if one video is played more than once.
-# The image_player only displays images for the duration configured in this file under the "image_player" section.
+# The image_player only displays images and for the duration configured in this file under the "image_player" section.
 # The default is omxplayer.
 video_player = omxplayer
 #video_player = hello_video
 #video_player = image_player
 
-# Where to find movie files.  Can be either usb_drive or directory.  When using
-# usb_drive any USB stick inserted in to the Pi will be automatically mounted
-# and searched for video files (only in the root directory).  Alternatively the
-# directory option will search only a specified directory on the SD card for
-# movie files.  Note that you change the directory by modifying the setting in
+# File Reader Location
+# Where to find media files.  Can be usb_drive, directory or usb_drive_copymode.  
+# When using usb_drive any USB stick inserted in to the Pi will be automatically 
+# mounted and searched for media files (only in the root directory).  
+# Alternatively the directory option will search only a specified directory on the SD 
+# card for media files.  
+# Note that you still need to change the directory by modifying the setting in
 # the [directory] section below.  The default is usb_drive.
 file_reader = usb_drive
 #file_reader = directory
 #file_reader = usb_drive_copymode
 
-# Copy-Mode:
-# If you enable this mode, movies are copied from the usb stick to the path specified
-# in the [directory] section below.
-# see additonal settings for copy-mode in the [copymode] section
-
-# The rest of the configuration for video looper below is optional and can be 
-# ignored.
+# Note on usb_drive_copymode:
+# If you enable this mode, media files are copied from the USB stick to the path 
+# specified in the [directory] section below.
+# see additional settings for copy-mode in the [copymode] section
 
+# On Screen Display (OSD)
 # Control whether informative messages about the current player state are
-# displayed, like the number of movies loaded or if it's waiting to load movies.
+# displayed, like the number of media files loaded or if it's waiting to load them.
 # Default is true to display these messages, but can be set to false to disable
 # them entirely.
 osd = true
 #osd = false
 
-#Below you can set for how many secounds the osd (and countdown) is displayed after files are found
+# Below you can set for how many secounds the osd (and countdown) is displayed after files are found
 countdown_time = 5
 
-# Below you can set a timout time (in seconds) that is waited between each videos
+# Below you can set a wait time (in seconds) that is waited between each video.
 # wait time is not honored for the first video that plays after starting a new playlist (e.g. after plugging in usb drive)
 # when using a self looping player like hello_video wait_time is not waited between each repeat of one video but between different videos
 # with omxplayer wait_time will also happen between every repeat of a video
 wait_time = 0
 
-# To play random playlist.
+# To play files in random order set this to true
 is_random = false
+#is_random = true
 
 # resume last playlist item after restart
 resume_playlist = false
 #resume_playlist = true
 
 # Control the program via keyboard
-# If enabled, hit ESC key to quit the program anytime (except countdown).
+# If enabled, hit the ESC key to quit the program anytime (except countdown). See the readme for more keyboard commands.
 keyboard_control = true
 #keyboard_control = false
 
 # Set the background to a custom image
 # This image is displayed between movies or images
-# it image will be scaled to the display resolution and centered
+# an image will be scaled to the display resolution and centered. Use i.e.
 # bgimage = /home/pi/loader.png
 bgimage = 
 
-# Change the color of the background that is displayed behind movies (only works
+# Change the color of the background that is displayed behind videos (only works
 # with omxplayer and the image_player).  Provide 3 numeric values from 0 to 255 separated by a commma
 # for the red, green, and blue color value.  Default is 0, 0, 0 which is black.
 bgcolor = 0, 0, 0
@@ -85,11 +91,6 @@ fgcolor = 255, 255, 255
 console_output = false
 #console_output = true
 
-# Directory file reader configuration follows.
-[directory]
-
-# The path to search for movies when using the directory file reader.
-path = /home/pi/video
 
 # USB drive file reader configuration follows.
 [usb_drive]
@@ -103,10 +104,19 @@ mount_path = /mnt/usbdrive
 readonly = true
 
 
+# Directory file reader configuration follows.
+[directory]
+# The path to search for movies when using the directory file reader.
+# (see the file_reader section above to enable it)
+path = /home/pi/video
+
+
+# Copy-mode file reader configuration follows.
 [copymode]
-# this setting controls what happens when a usb drive is plugged in while in copymode
-# the default setting "replace" clears out the video directory and then copies the files from the drive
-# with add files from the drive are copied to the directory in addition to existing files
+# this setting controls what happens when a USB drive is plugged in while in copymode 
+# (see the file_reader section above to enable it)
+# the default setting "replace" deletes any files in the video directory and then copies the files from the USB drive
+# with 'add' files from the drive are copied to the directory in addition to existing files
 # NOTE: files with the same name are always overwritten
 # copymode setting can be overridden by placing a file named "replace" or "add" on the drive (extension does not matter)
 
@@ -118,16 +128,16 @@ mode = replace
 copyloader = false
 #copyloader = true
 
-# this setting defines a "password" that has to exists as a file (with the password as a filename) (extension does not matter)
-# on the usb drive for the videolooper to accept videos from the usb drive
-# default is videopi - you should consider changing it - if it is emtpy no check will be performed
+# this setting defines a "password" that has to exist as a file (with the password as a filename) (extension does not matter)
+# on the USB drive for the videolooper to accept videos from the USB drive
+# default is videopi - you should consider changing it - 
+# if it is empty no check will be performed
 # for maximum compatibility use only ascii characters
 password = videopi
 
 
 [playlist]
-# This setting allows for a fixed playlist.
-
+# This setting allows for a fixed playlist. See the example.m3u file in assets for the syntax.
 # Path to the playlist file.
 # If you enter a relative path (not starting with /) it is considered relative to the selected file_reader path (directory or USB drive).
 # Leave empty to not use a playlist and play all the files in the file_reader path (directory or USB drive).
@@ -178,7 +188,8 @@ sound = both
 #sound = local
 #sound = alsa
 
-# Sound volume output for the video player will be read from  a  file  near  the
+# Specify a sound volume output for the video player. 
+# The volume will be read from a file near the
 # video files. If the file does not exist, a default volume of 0db will be used.
 # To use this feature create a file in the same directory as the videos and name
 # it the value defined below (like 'sound_volume' by default), then inside the
@@ -199,16 +210,19 @@ title_duration = 10
 # Any extra command line arguments to pass to omxplayer.  It is not recommended
 # that you change this unless you have a specific need to do so!  The audio and
 # video FIFO buffers are kept low to reduce clipping ends of movie at loop.
-# Run 'omxplayer -h' to have the full list of parameters.
+# Run 'omxplayer -h' to have the full list of parameters or see
+# https://github.com/popcornmix/omxplayer#synopsis for all available options
 extra_args = --no-osd --audio_fifo 0.01 --video_fifo 0.01 --align center --font-size 55
 
+
 # hello_video player configuration follows.
 [hello_video]
 
 # List of supported file extensions.  Must be comma separated and should not
 # include the dot at the start of the extension.
 extensions = h264
 
+
 # image player configuration follows
 [image_player]
 
@@ -223,6 +237,6 @@ duration = 5
 scale = true
 #scale = false
 
-# Controls if images should be displayed in the center. Default: true
+# Controls if images should be displayed centered. Default: true
 center = true
 #center = false