Manual_1p3p5a Manual
User Manual: Pdf
Open the PDF directly: View PDF .
Page Count: 111
Version 1.3.5a, 1 May 2018
Track changes base is 1.3.4c
Pi Presents
A Multi-media Interactive Display and Animation Toolkit
for Museums, Visitor Centres and more…..
Running on the Raspberry Pi
Ken Thompson
http://pipresents.wordpress.com
Page 1
Version 1.3.5a, 1 May 2018
Contents
1
Introduction ...................................................................................................... 6
1.1
Acknowledgements ..................................................................................... 8
2
Installation ........................................................................................................ 9
3
Try Some Examples ......................................................................................... 9
3.1
4
Terminating Pi Presents ............................................................................ 13
The Pi Presents Profile Editor ....................................................................... 14
4.1
Using the Editor......................................................................................... 14
4.1.1
The Displays ...................................................................................... 14
4.1.2
Profile Menu ....................................................................................... 15
4.1.3
Show Menu ........................................................................................ 15
4.1.4
Medialist Menu ................................................................................... 15
4.1.5
Track Menu ........................................................................................ 15
4.1.6
OSC Menu ......................................................................................... 16
4.1.7
Tools Menu ........................................................................................ 16
4.1.8
Options Menu ..................................................................................... 16
4.1.9
Editor Command Line Options ........................................................... 17
4.2
Making Profiles ......................................................................................... 17
4.2.1
Making Profiles Portable .................................................................... 17
4.2.2
Using the SD Card for Profiles ........................................................... 18
4.2.3
Using the Editor on a Windows PC .................................................... 18
4.2.4
Using a USB Stick for Profiles ............................................................ 18
4.2.5
Developing Profiles using a Monitor with Different Pixel Dimensions.. 19
5
The Components of Pi Presents ................................................................... 19
5.1
Introduction ............................................................................................... 19
5.2
Shows ....................................................................................................... 21
5.2.1
Mediashow and Artmediashow........................................................... 21
5.2.1.1
Controls and Commands............................................................. 23
5.2.1.2
Triggers....................................................................................... 25
5.2.1.3
Fields .......................................................................................... 26
5.2.2
Menu .................................................................................................. 33
5.2.2.1
Controls and Commands............................................................. 33
5.2.2.2
Fields .......................................................................................... 33
5.2.3
Liveshow and Artliveshow .................................................................. 34
5.2.4
Radiobuttonshow ............................................................................... 35
5.2.4.1
Controls and Commands............................................................. 36
5.2.4.2
Fields .......................................................................................... 36
5.2.5
Hyperlinkshow.................................................................................... 38
5.2.5.1
Controls and Commands............................................................. 39
5.2.5.2
Touchscreens and Soft Buttons .................................................. 40
5.2.5.3
Fields .......................................................................................... 41
5.2.6
Start Show ......................................................................................... 43
5.3
Medialists .................................................................................................. 43
5.4
Tracks ....................................................................................................... 44
5.4.1
Track Location Names ....................................................................... 44
5.4.2
Anonymous and Labelled tracks ........................................................ 45
5.4.3
Show Track ........................................................................................ 45
5.4.4
Image Track ....................................................................................... 45
Page 2
Version 1.3.5a, 1 May 2018
5.4.4.1
Image Window ............................................................................ 47
5.4.5
Video Track ........................................................................................ 49
5.4.5.1
Video Playout .............................................................................. 51
5.4.6
Audio Track ........................................................................................ 51
5.4.7
Web Tracks ........................................................................................ 53
5.4.7.1
Browser Commands.................................................................... 55
5.4.7.2
Full screen Integrated Browser Displays ..................................... 56
5.4.8
Message Tracks ................................................................................. 57
5.4.9
Show Track ........................................................................................ 59
5.4.10 Menu Track ........................................................................................ 59
6
Black Box Operation ...................................................................................... 63
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
Command Line Options............................................................................. 63
Specify a Profile ........................................................................................ 65
Specify a Home Directory .......................................................................... 65
Using GPIO to Control Pi Presents............................................................ 65
Disable Screen Blanking ........................................................................... 66
Start Pi Presents when Power is applied to the Pi ..................................... 66
Shutdown the Raspberry Pi from the GPIO ............................................... 67
Controlling the Monitor .............................................................................. 67
7
Exiting Pi Presents and Shutdown of the RPi .............................................. 67
8
Controlling Shows.......................................................................................... 68
8.1
Controlling Track Movement in Individual Shows ...................................... 68
8.2
Opening and Closing Shows and Show Control ....................................... 69
8.2.1
Opening and Closing Shows .............................................................. 69
8.2.2
Sending Events between Shows ........................................................ 70
8.2.3
Other Uses of Show Controls ............................................................. 70
8.3
Time Of Day Scheduler ............................................................................. 70
8.4
Concurrent Shows..................................................................................... 72
8.4.1
Control with Concurrent Shows .......................................................... 72
8.4.2
Limitations on Concurrency ................................................................ 73
9
Touchscreens and Soft Buttons ................................................................... 73
9.1
9.2
9.3
Controlling Shows with a Touchscreen...................................................... 73
Click Areas ................................................................................................ 74
Soft Buttons .............................................................................................. 74
10
Run-Time Commands ................................................................................. 75
11
Providing Dynamic Content in a Liveshow ............................................... 76
12
Counters ...................................................................................................... 76
13
Animation Control ...................................................................................... 77
14
Input/Output (I/O) Plugins .......................................................................... 78
14.1
Enabling a Standard I/O Device ............................................................. 79
14.2
Configuring Inputs and Output Drivers ................................................... 80
14.2.1 Interfacing with GPIO using pp_gpiodriver.py..................................... 80
14.2.2 Interfacing with a Remote Control or Keypad using
pp_inputdevicedriver.py ................................................................................... 82
14.2.3 Interfacing with a Serial Link using pp_serialdriver.py ........................ 82
14.2.4 Interfacing with I2C devices using pp_i2cdriver.py ............................. 84
14.2.5 Configuring Tkinter Keyboard Keys using pp_kbdriver.py .................. 85
14.2.6 Advanced Interfacing with a Keyboard using pp_kbddriver_plus.py .. 86
14.2.7 Configuring Touch/Click Areas ........................................................... 87
Page 3
Version 1.3.5a, 1 May 2018
14.3
Writing I/O Plugins ................................................................................. 88
14.3.1 Configuring and Registering an I/O plugin .......................................... 88
14.3.2 Class .................................................................................................. 88
14.3.3 Methods ............................................................................................. 89
14.3.4 Example ............................................................................................. 91
15
Remote Control using OSC ........................................................................ 91
15.1
15.2
15.3
15.4
Sending and Receiving Commands via OSC ......................................... 92
OSC Fundamentals ............................................................................... 92
Configuring OSC ................................................................................... 94
oscremote and oscmonitor..................................................................... 95
16
Track Plugins .............................................................................................. 96
17
Remote Management .................................................................................. 98
17.1
17.2
17.3
18
Setting up for Remote Use..................................................................... 98
.Using the Manager ............................................................................. 100
Using the Web Editor ........................................................................... 102
Email Alerts ............................................................................................... 102
18.1
18.2
Setting Up Email Alerts ........................................................................ 102
Using Email Alerts ............................................................................... 103
19
Hardware Requirements........................................................................... 103
20
Updating Pi Presents ................................................................................ 104
20.1
20.2
21
Updating Profiles ................................................................................. 104
Updating Pi Presents ........................................................................... 104
Debugging, Statistics, Bug Reports and Feature Requests .................. 104
21.1
21.2
Statistics Production ............................................................................ 104
Debugging Profiles .............................................................................. 105
22
Gotchas and Known Problems ................................................................ 106
23
Converting Version 1.2 to 1.3................................................................... 108
Page 4
Version 1.3.5a, 1 May 2018
Copyright Notice
This manual and the Pi Presents software are copyright Ken Thompson. For licence
conditions see:
https://github.com/KenT2/pipresents-gapless/blob/master/licence.md
Raspberry Pi is a trademark of the Raspberry Pi Foundation
http://www.raspberrypi.org
Page 5
Version 1.3.5a, 1 May 2018
1 Introduction
Pi Presents is a toolkit for creating and deploying multi-media interactive displays
with animation control facilities. It was originally intended for Museums and Visitor
Centres but has already found uses in hospitals, shops, schools, art installations,
libraries and more…..
Until the Raspberry Pi arrived buying or constructing something even as simple as an
interactive audio player was expensive. The Raspberry Pi with its combination of
Linux, GPIO and a powerful GPU is ideal for black box multi-media applications; all it
needed was a program to harness its power in a way that could be used by nonprogrammers.
There are a number of digital signage applications for the Raspberry Pi which are
limited to slideshows and must take their media from the internet. Pi Presents is
different; it is a toolkit which allows construction of many types of interactive
presentation applications by using a simple to use editor running on a browser either
on a Pi or remotely.
The Pi Presents toolkit supports the types of show commonly seen in museums;
each of these can be configured to meet your individual requirements.
Some uses:
Animation or interpretation of exhibits by triggering a sound, video, or
slideshow from a button, keyboard or other GPIO input.
While playing media, GPIO outputs can be used to control external devices
such as lights, animatronics etc.
A multimedia slideshow for a visitor centre. Images, videos, audio tracks, and
messages can be displayed. Repeats can be at intervals or at specified times
of day.
Slideshows to be interrupted by the visitor and a menu of further content
presented.
A show for kiosks where content can be initiated by pressing one of a number
of buttons.
Facilities to construct ‘hyperlinked’ shows commonly seen on touch screens
in museums.
Construct a 'powerpoint' like multi-media presentation where progress
through slides is manually controlled by buttons or keyboard.
Basic digital signage with the ability upload image, video or audio tracks over
a network for display in a repeating show.
Multi-window displays, displaying several types of content on a single screen
Page 6
Version 1.3.5a, 1 May 2018
Run a selection of shows at different times, days of the week, and special
days in a year.
Construct a network of Pi Presents applications controlled through the Open
Sound Control (OSC) protocol or control Pi Presents from remote computers,
tablets or smartphones.
Manage Pi Presents and edit profiles remotely using any browser (Local Area
Network required). Receive email alerts reporting the status of deployed Pi
Presents applications.
Foreign language support. All text shown to the audience is configurable.
Once set up Pi Presents is easy to use and does not require a network:
Shows can be prepared using a simple to use editor.
Will operate on a Model A or A+ Raspberry Pi (but see hardware
requirements).
No need to modify the Pi’s SD card after initial installation. All media and
configuration options can be kept on a removable USB stick. Installing an
updated application can be as simple as inserting the USB stick.
Video output can use HDMI or composite video selected using the normal Pi
setup procedure. As Pi Presents can be started and shutdown without a
keyboard a monitor is not required.
Audio track output is selectable between HDMI and analogue and can be
output from left, right or stereo speakers on a per track basis. A number of
tracks can be played simultaneously to different speakers each with
presettable volume.
Pi Presents, out of the box, runs as a desktop application on the Raspberry Pi using
the keyboard for control. However with a little bit of Linux magic, which is explained in
this manual, it can be made to run as a black box application with control from GPIO
or remotely via OSC. Black box features include:
Disabling screen blanking and the mouse pointer.
Full screen operation without window decorations
Completely headless operation without a keyboard, mouse or buttons (except
perhaps a shutdown button if you do not want to risk SD Card corruption)
Black box control can be by buttons, PIR, or any source of digital inputs. It is
straightforward to make your own controls.
Mouse compatible touchscreens are supported if drivers are available for the
Raspberry Pi. Alternatively a keyboard and mouse can be used. Pi Presents
Page 7
Version 1.3.5a, 1 May 2018
has been designed such that it is possible to add drivers written in Python for
other forms of input and output such as RS232 and I2C.
Automatic start up when power is applied to the Pi
Safe shutdown without using keyboard or mouse
Automatic opening and closing of shows and shutdown of the Pi at specified
times of day. The time of day scheduler is programmable for different
schedules on different days of the week, or month, or for special days in the
year.
Remote control of a Pi Presents application using Open Sound Control from
another Pi Presents or any computer with a suitable OSC application.
1.1 Acknowledgements
Douglas Otwell for dbus control of omxplayer
https://github.com/Douglas6/omxcontrol
Davide Rosa for RemI – Remote Interface, a toolkit for writing browser based gui’s in
Python
https://github.com/dddomodossola/remi
Johannes Baiter (jbaiter) for pyomxplayer based on Noah's pexpect
Numerous people on the Raspberry Pi forum and websites, particularly
StackOverflow, who have unwittingly provided me with solutions to many technical
problems and taught me Python.
Bullets from http://www.enterprise-dashboard.com/tag/red-green-yellow-alert/
Icons from http://www.fatcow.com/free-icons
Buttons from http://www.freewebsitebuttons.com
The Raspberry Pi Foundation for the first affordable machine that plays video, audio
and has GPIO.
Having been introduced to open source software through the Raspberry Pi I was
amazed at the time and effort which so many people put in to produce software for
others, so I thought it worthwhile to do the same with Pi Presents. I am glad I did
because the feedback I have had from users and potential users has given me so
many good ideas for extensions to Pi Presents. Needless to say I have been so busy
producing Pi Presents that I have not had time to use it for my own intended projects,
however one day I am sure I will ( I now have two three) .
Page 8
Version 1.3.5a, 1 May 2018
2 Installation
The installation instructions are in the README.md file. Pi Presents requires
Raspbian Stretch and should always use the latest Foundation Raspbian release and
MUST BE INSTALLED AND RUN FROM THE PIXEL DESKTOP.
3 Try Some Examples
Download the examples from the pipresents-gapless-examples github repository as
described in the README.md file.
N.B. Pi Presents must be run from the PIXEL desktop (you must have executed
startx either from the command line or set ‘boot to desktop’ in raspi-config) . From a
terminal window opened in the pipresents directory type:
python pipresents.py –p pp_mediashow_1p3
You will see a continuous looping show in a small window. The small window is
useful for development purposes; you can adjust its size by editing pipresents.py,
around line 45. You can expand the display to nearly full screen by using the
appropriate window decoration. If however you want to see the show truly full screen
without borders then use the -f command option and –b to disable screen blanking:
python pipresents.py –p pp_mediashow_1p3 –f -b
The mediashow example and all the other examples are designed for a 1920*1080
display. If you have a smaller resolution display some of the text and part of the
larger images will disappear off the edges of the display. Pi Presents does not
automatically adjust for screen resolution; you will need to use the Pi Presents editor
to adjust text position and font sizes , and to resize images external to Pi Presents.
The pipresents-gapless-examples repository has examples of how to use Pi
Presents.
You can use the bash script examples.sh to execute the examples, just type
./examples.sh from a terminal window open in the /pipresents directory or copy the
examples.desktop file from /pipresents to your desktop. You will need to make
examples.sh executable.
The examples use the following keys:
Up or Down Cursor- move through a menu.
Up or Down Cursor - Move through a mediashow show. Can also be used to
skip to the next or previous track in an automatic mediashow. The movement
circles around at the start and end of a show.
Return – Play the selected menu entry or a child track.
Escape – Stops the current track/show in an intuitive manner.
Spacebar - in an image, video, or audio track, toggle pause.
CTRL-BREAK always exits Pi Presents. (Duplicated by the Close window
icon or Alt+F4)
All examples use a selection of media tracks which are in /home/pi/pp_home/media.
The profiles are in /home/pi/pp_home/pp_profiles. In each profile the
Page 9
Version 1.3.5a, 1 May 2018
pp_showlist.json file specifies the look and feel of each show; other files specify the
media to use. The files can be viewed in a text editor but it is much better to edit
them using Pi Present's own editor described in Section 4.
Other optional files in the profile, screen.cfg, gpio.cfg, keys.cfg, osc.cfg and
schedule.json customise other aspects of Pi Presents.
How the profiles work is explained in detailed later so do not worry if you do not
understand them, just enjoy what Pi Presents is capable of.
The examples:
pp_mediashow_1p3
The profile you have just run. The show will start immediately, progress
automatically, and then repeat. Use the Up and Down cursor keys to skip
tracks. The example demonstrates the types of track and additional
information that can be added to the primary content.
pp_menu_1p3
The example demonstrates all the menu formats available in Pi Presents. The
second level menus, and any show which runs from another show are called
subshows. Use the Up and Down cursor keys to traverse the menu then
press Return to Start a track or sub-menu, and Escape to terminate it.
pp_exhibit_1p3
This demonstrates how to trigger a mediashow from a PIR. When started, the
screen will be blank. Triggering the PIR input (opening a contact connected to
0 volts on P1-11) or pressing a button (closing a contact connected to 0 volts
on P1-18) will start a one shot mediashow and then wait for the trigger in
order to repeat the show.
The example uses the gpio.cfg file in the profile which has pins P1-18 and P111 bound to the symbolic name PIR. This name is then associated with
Trigger for Start in the mediashow.
The example also uses the Return key as a trigger input so you can see the
effect without using the GPIO pins. The keys.cfg file in the profile overrides
the default keys.cfg and binds the Return key to the symbolic name PIR.
BEWARE: Do not use the GPIO pins until you have read Section 6.4
pp_openclose_1p3 (New in Version 1.3)
A single shot mediashow with a different method of triggering. Useful if you
want a track to play when opening a box or door, and stop when it is closed.
gpio.cfg in the profile uses p1-18 for this task.
pp_onerandom_1p3 (New in Version 1.3)
When triggered plays a single track randomly chosen from the medialist .
pp_magicpicture_1p3 (Rewritten in Version 1.3.2a)
A still picture of a person is seen in a picture frame. When a button is pressed
the picture comes to life as a video is played. The effect is achieved by
pausing the video just after the first frame. I don’t have a video of a person so
Suits will have to do!
Page 10
Version 1.3.5a, 1 May 2018
pp_interactive_1p3
This combines a mediashow and a menu. The mediashow is run continuously
but every track has a hint showing that a menu can be triggered by the Return
key. Pressing Escape from the menu returns to the mediashow. A track or
show which is accessible from any track in a mediashow is called a child.
pp_presentation_1p3
The mediashow is configured as a manually controlled presentation. Use the
Up and Down cursor keys to traverse through it. Pi Presents cannot use
Powerpoint presentations but Powerpoint presentations can be saved as jpeg
images.
pp_liveshow_1p3
While the Liveshow is running place some video files, audio files, or images
into the directory /home/pi/pp_home/pp_live_tracks and watch them
miraculously appear. A liveshow is a mediashow without pre-defined media.
pp_liveshowempty_1p3 (new in 1.3.2a)
Demonstrates the increased flexibility in handling liveshows with an empty
tracks directory. An empty live tracks directory will play a ‘list empty’ track and
execute the ‘on empty’ and ‘on not empty’ Show Control commands.
pp_radiobuttonshow_1p3
Think of the navigation method in a Radiobuttonshow as being like a car radio
channel changer. Press keys 1-4 or GPIO buttons to play a track and Escape
to return to the main screen.
Controls defined in the Radiobutttonshow profile allow for both keyboard keys
and buttons to be used to select a track. A gpio.cfg file is included in the
profile to bind four GPIO pins to entries and one to the Stop Operation.
pp_hyperlinkshow_1p3
The Hyperlinkshow works something like a set of web pages with links
between them and Back and Home buttons. All of the ‘story telling’
applications in museums appear to use this navigation technique.
The show is aimed at touchscreens. The on screen buttons are touch
sensitive areas which, for testing purposes, are also sensitive to mouse
clicks. The file screen.cfg in the profile defines the buttons and the symbolic
names of their input events. If using ‘Soft Keys’ the show could be controlled
by GPIO pins by binding pins to the symbolic names in a gpio.cfg file.
pp_audio_1p3
This mediashow demonstrates the capabilities of the audioplayer. You will
need speakers connected to hdmi and analogue ports to fully appreciate it. It
plays tracks to different speakers; it also demonstrates the use of Run-Time
controls to control volume from keyboard (8 and 9) or GPIO pins and mute
(keys 1 and 2). For this reason it has keys.cfg and gpio.cfg files in the profile,
pp_web_1p3
A demonstration of the web browser capabilities. Ideally an internet
connection is required. Because the integration between Pi Presents and the
browser is not good, it will take a long time for the browser to open and, if you
Page 11
Version 1.3.5a, 1 May 2018
need to interact with Pi Presents when the browser is displayed you will need
to click on its window first.
pp_concurrent_1p3
This application demonstrates concurrent show playing capabilities. There are
two mediashows running simultaneously. The mediashow showing images
must be controlled from the keyboard while the concurrent mediashow
containing audio tracks has its controls disabled and is played continuously.
pp_multiwindow_1p3 (New in Version 1.3)
This application demonstrates concurrent show playing capabilities where
many shows display content. There are 4 mediashows and a menu running
simultaneously. The menu must be controlled from the keyboard while the
concurrent mediashows have their controls disabled and are played
continuously. The number of concurrent shows is limited only by the power of
the Pi. In the example:
• background - provides the static background
• audio - plays the background audio
• text - is a changing text only mediashow
• slideshow – multimedia automatic slideshow
• menu – interactive menu
The show is set up for remote control by OSC, see Section 15.4
pp_artmediashow_1p3(New in Version 1.3)
A mediashow which features gapless transitions without freezing the picture
at the end of video tracks. Has limited features but could be useful for ‘artistic’
applications.
pp_artliveshow_1p3(New in Version 1.3)
A liveshow which features gapless transitions without freezing the picture at
the end of video tracks. Has limited features but could be useful for ‘artistic’
applications.
pp_subshow_1p3
Demonstrates how to use subshows to segment a larger mediashow.
pp_timeofday_1p3 (Greatly enhanced from Version 1.2)
Opens and closes two mediashows at different times of day and then exits Pi
Presents. This is all controlled by the schedule.json in the profile. To make
this demonstration work whatever the day and time you test it the date and
time is simulated by setting “simulated-time” to “yes” in schedule.json. Make
a backup copy of schedule.json and then alter the date and time to see the
effects. Note morning opening only on Xmas day, just like English pubs!
pp_plugin_1p3 (Plugin API has been modified for Version 1.3)
Demonstrates the operation of track plugins. Track plugins are Python
modules with a defined API which allow you to produce dynamic displays
particularly clocks and from data scraped from the web. Before using the
liveshow copy the .cfg files from the /media directory to the /pp_live_tracks
directory.
pp_showcontrol_1p3
Page 12
Version 1.3.5a, 1 May 2018
Demonstrates the use of Show Control to start and stop one concurrent show
from another. The show is set up to control another Pi by OSC, see Section
15.4
pp_showcontrolevent_1p3
Demonstrates the use of the Show Control Event command to pause and unpause a track using pause-on and pause-off commands
pp_clickarea_1p3
Demonstrates use of click areas in each type of show and the use of Soft
Buttons. In the Radiobuttonshow click areas are selectively disabled by
individual tracks. Soft Buttons has a keys.cfg file which allows keys 1 and 2 to
select the two tracks. When deployed properly there would be two GPIO
buttons mounted adjacent to the left edge of the screen and a gpio.cfg file to
associate the buttons with the symbolic names.
pp_animate_1p3 (Animation commands have changed for version 1.3)
Demonstrates the use of Animation Control by setting P1-11 to On at the start
of a track and to Off at the end. To achieve this it has a gpio.cfg file in the
profile. BEWARE: Ensure P1-11 can safely be used as an output before
running this.
pp_shutdown_1p3
A mediashow that demonstrates how to use Show Control to shut down the Pi
It displays a message track and then when the Down Cursor is pressed starts
a track that shuts down the Pi immediately.
pp_videoplayout_1p3
A demonstration of three types of show that can be used as a video playout
system in theatres or television stations. The key aspect is that videos are
loaded and paused just before the first frame so that pressing the g key which
executes the Go command causes the video to start immediately. Audio files
can be similarly played provided they are implemented as video tracks. See
Section 5.4.5.1
pp_counters_1p3 (new for version 1.3.3a)
Demonstrates the commands for control of counters and use the track plugin
which can access and display values of counters
pp_quiz_1p3 (new for version 1.3.3a)
Demonstrates the use of counters and a Hyperlinkshow to implements a quiz
pp_osc_1p3 (new for version 1.3.3c)
Demonstrates the show control commands for remote control via OSC
3.1 Terminating Pi Presents
You can terminate Pi presents by pressing Ctrl+Break or Alt+F4, or clicking on the
'Close' icon. Terminate is aimed at aborting Pi Presents even in abnormal situations.
For other ways of closing Pi Presents or shutting down the RPi see Section 7
Page 13
Version 1.3.5a, 1 May 2018
Some keyboards do not have a BREAK key; it is possible to configure another key to
exit Pi Presents by editing the keys.cfg file to bind another key to the pp-terminate
symbolic name as described in Section 14.2.5
4 The Pi Presents Profile Editor
This manual is for the new web based editor which replaces the Pi only editor in Pi
Presents - Next. The web based editor is browser based so can be used from a
remote computer in addition to local use. Using the web based editor remotely and
details of the minor differences to look and feel are described in Section 17.3
Profiles can be created and edited using the Pi Presents editor. For use on the Pi the
command is:
python pp_web_editor.py
This will open the Chrome browser and display the editor gui.
When using the editor you will need to supply show references, track references and
file names. It is advisable not to create names beginning with pp- or pp_ to avoid
clashes with names used by Pi Presents.
4.1 Using the Editor
4.1.1 The Displays
Select one of the example profiles using the Profile>Open menu. In the directory
browser click on the text of the example (e.g. pp_mediashow_1p3) and press OK.
Unlike the previous editor do not open the directory.
The top left panel displays the shows in the profile
The bottom left panel shows the medialists in the profile, click on one of the
entries to select it.
The right-hand panel shows the tracks in the selected medialist.
The selected entries are shown with a red background. Click the 'Edit Show' button
adjacent to the left-hand panel to edit the selected show and the 'Edit' button
adjacent to the right-hand panel to edit the selected track.
Edits are saved to disc when OK is pressed, use Cancel if you want to exit without
saving.
You can run pipresents.py and pp_web_editor.py concurrently from two terminal
windows so the effect of any edits can quickly be seen. You will need to restart
pipresents.py to see the effect of the updates made by the editor.
If you are going to edit the examples then first make a copy of them by using the
PCManFM File Manager to access
/home/pi/pp_home/pp_profiles
Page 14
Version 1.3.5a, 1 May 2018
and to copy a profile directory.
4.1.2 Profile Menu
Profile>Open - displays a directory viewer to select a profile for editing. The profiles
displayed are those in the home + offset directory defined in the Options>Edit menu.
Profile>Validate - Validate the Profile. Font and Colour fields are currently not
validated and if you edit the .json files with a text editor you are on your own!
Profile>Copy To – Copies a profile
Profile>Delete – Delete a profile
Profile>New from Template - lists templates for all types of show. The templates
have example tracks so they will run un-edited but some will be missing configuration
files. Examples of these can be copied from:
and
/home/pi/pipresents/pp_io_config
/home/pi/pipresents/pp_resources/pp_templates
4.1.3 Show Menu
Show>Add - Add a new show, and a medialist with the same name. The show type
of an existing show cannot be edited.
Show>Copy To - Copy the show, creating an empty medialist for the show
Show> Edit - Duplicates the Edit Show button
Show>Delete - Deletes the show from the profile, no going back!
4.1.4 Medialist Menu
Medialist>Add - Add a new medialist. The .json extension is added if not included.
Medialist>Copy To – Copy the medialist
Medialist>Delete - Deletes the medialist from the profile, no going back!
4.1.5 Track Menu
Track>Add File
Adds one or more track entries containing media files to the end of the medialist.
These may be images, videos or audio tracks. The editor automatically calculates the
file location and track type. If either of these is unacceptable or the media file
extension is rejected then use Track>New to add a blank track of the required type.
The list of extensions that are used to select track type is in the first few lines of the
pp_definitions.py source. Please raise a bug report if these are inadequate.
Track>Add Dir
Page 15
Version 1.3.5a, 1 May 2018
Similar to Add File, except that all eligible tracks in the directory are added to the
medialist.
The list of eligible extensions that is used to select tracks and their types is in the first
few lines of the pp_definitions.py source. Please raise a bug report if these are
inadequate.
Track>New
Adds a blank track of the selected type to the end of the medialist.
Track>Edit
Duplicates the Edit Button
Track>Copy
Copies a track
Track>Delete
Deletes the track from the medialist, no going back!
4.1.6 OSC Menu
OSC>Create
Creates an empty osc.cfg file in the profile in the directory pp_io_plugins
OSC>Edit
Edits osc.cfg.
4.1.7 Tools Menu
Tools>Update All
Update the version of all profiles in the current home + offset directory, see Section
20.
4.1.8 Options Menu
Options>Edit
Edit the editor options:
Pi Presents Home Directory
This is an important option which must be set to the directory in which any
profile directories and relative media is to be assembled. Out of the box it is
set to /home/pi/pp_home. If you choose an alternative setting for this then
ensure that the directory /pp_profiles is created inside the chosen /pp_home.
Initial Media Directory
This is just a helper setting to define where 'Add Track' and 'Add from Dir'
start their browsing.
Offset for current profiles
This advanced option allows profiles to be separated into directories under
/pp_home/pp_profiles and readily accessed so an offset of /1p3_examples
defaults ‘open’ to /pp_home/pp_profiles/1p3_examples
Page 16
Version 1.3.5a, 1 May 2018
4.1.9 Editor Command Line Options
one of :
If none of these are specified then -l is assumed.
-r --remote
-l --local
-n --native
local – the editor server is run and a browser is opened on the
RPi (ip=127.0.0.1)
remote – the editor server is run with the IP address of the RPi
(e.g. 192.168.1.67) it can be accessed remotely from a browser
on another computer using http://192.168.1.67:8082
native – the editor is run natively on the RPi without a browser.
Requires qt5 and pyview to be installed (which I failed to achieve)
4.2 Making Profiles
Application data is kept is a directory called /pp_home. /pp_home must contain a
directory /pp_profiles in which profiles are stored.
A profile is a directory which contains the information needed to configure a single
application of Pi Presents. It must contain a pp_showlist.json file and one or more
medialist (.json) files. The pp_showlist.json file contains a number of sections, a
'start' show section and a number of sections each defining a user generated show.
Each section in the pp_showlist.json file defines the look and feel of a show and how
they link together. Medialist (.json) files in a profile define the content each show and
some per track look and feel information.
To make profiles portable all media is best kept either under the directory /pp_home
or alternatively inside a profile. In both cases it is recommended that media is stored
in a sub-directory, by convention named media. Media stored like this is referenced
by relative file paths in a profile e.g. +/media/myimage.jpg or @/media/myimage.jpg
The default location of /pp_home is /home/pi; this will need to be overridden by
command line options if you are using a USB stick.
A profile may optionally contain other configuration files such as schedule.json also
an optional directory /pp_io_config which contains Input/output configuration files
such as gpio.cfg. A readme.txt file can be included to allow the profile to be
documented.
4.2.1 Making Profiles Portable
Profiles and their media can be moved between different drives without breaking the
references between shows and their media tracks. This is necessary if a profile is
prepared on a Pi on a SD card and moved to a USB Stick for operational use.
To achieve portability media tracks should be stored under the /pp_home directory,
preferably in sub-directories or alternatively in a profile, by convention in a directory
called media. If tracks are stored in these locations before the profile is prepared then
the Profile Editor will automatically compute the appropriate track reference:
Page 17
Version 1.3.5a, 1 May 2018
If the file is below the home directory (…../pp_home), as defined in the
Options>Edit menu then the file reference will look like '+/track_to_play.mp4'
If the track is in the profile then the file reference will look like
'@/media/track_to_play.mp4’
Otherwise the reference will look like '/home/pi/mymedia/track_to_play.mp4';
an absolute reference.
Absolute references do have their uses, for example in specifying internet url's e.g.
http://www.mysite.com/ track_to_play.mp4
4.2.2 Using the SD Card for Profiles
This is very useful for developing applications on a Pi. To use the SD card for
developing and running profiles:
Create a directory /pp_home in the User Pi's home directory and inside that
create a directory called pp_profiles. You can also create a directory in
/pp_home called say, media, to hold media files.
In the Editor Options set the Pi Presents Data Home directory to
/home/pi/pp_home and the Initial Directory for Media to
/home/pi/pp_home/media
Copy media files to the /media directory
Using the editor create a new profile, call it myprofile, and edit it.
To run the profile type:
python pipresents.py -p myprofile
from a terminal window open in the pipresents directory.
When running Pi Presents from a desktop shortcut, or from an autostart file it is best
to specify the full path of pipresents and also the full path of the data home directory.
e.g.
python /home/pi/pipresents/pipresents.py -o /home/pi -p myprofile
4.2.3 Using the Editor on a Windows PC
Note: This applies to the old editor which is discontinued.
4.2.4 Using a USB Stick for Profiles
To run profiles from a USB stick copy /pp_home to the top level of a USB stick from
its location either on a Pi.
Page 18
Version 1.3.5a, 1 May 2018
Insert the USB stick into a Pi and run Pi Presents with the -o option set to
/media/pi/STICKNAME. STICKNAME is the drive name.
4.2.5 Developing Profiles using a Monitor with Different Pixel
Dimensions
The –s –screensize command line option assists with developing applications on a
host monitor that has different pixel dimensions to the target monitor. Use of this
option will cause Pi Presents to use the provided dimensions instead of the host
screen dimensions that it obtains from Raspbian.
All layout operations such as centring and warping images will use the
provided target dimensions.
If fullscreen mode is not in use a yellow rectangle will show the dimensions of
the target screen.
If fullscreen mode is in use then the display will be the size of the target
monitor placed at the top left of the host monitor. If the target dimensions are
greater than the host dimension then parts of the display will disappear.
5 The Components of Pi Presents
5.1 Introduction
Shows and Tracks
The Pi Presents toolkit has two building blocks - shows and tracks.
A show plays tracks; the list of tracks to be played is contained in a medialist which is
associated with the show, think of the medialist as an enhanced playlist.
The toolkit currently has seven types of show each optimised for a different purpose:
Mediashow - plays a sequence of tracks, usually automatically, but progress
can be manually controlled. Transitions between tracks are gapless but this is
achieved by freezing videos and images at the end of the track while the next
track is loaded.
Artmediashow – plays a sequence of tracks as in Mediashow with full gapless
capability. The next track is loaded while the previous track is playing hence
the tracks do not freeze at their end. The Artmediashow has no triggering
capability and does not support Child tracks or Subshows
Hyperlinkshow - Implements the touchscreen functionality that you see in
many museums.
Page 19
Version 1.3.5a, 1 May 2018
Radiobuttonshow - A simple kiosk show showing a navigation screen - press
one of many buttons to play a track.
Menu - Similar to a Radiobuttonshow but the track selection is by traversing a
menu using 'cursor' keys or a single button.
Liveshow - A Mediashow like show with dynamic remotely sourced content.
Artliveshow – uses remote content as in Liveshow and has full gapless
capability. The next track is loaded while the previous track is playing hence
the tracks do not freeze at their end. The Artliveshow has no triggering
capability and does not support Child tracks or Subshows
The toolkit currently has 'players' for five types of track each playing a different type
of media. All 'players' allow the primary media to be displayed in a window with an
optional background of plain colours, images, and text annotations. Players allow
animation to be controlled, track plugins to be written in Python, and for other
concurrent shows to be opened and closed.
video - plays videos using omxplayer
audio - plays audio tracks using mplayer
image - displays images in many different formats (.jpg etc.) (uses Python
Imaging Library)
message - a quick way to display text.
Web – runs an embedded web browser (uses uzbl)
Subshows and Child Tracks
In Pi Presents a show can be a track of its parent show; this is called a subshow.
Subshows have a number of uses which include:
Dividing a long mediashow into segments. Each segment is a show and a
parent mediashow contains the segment shows in its medialist.
A menu or radiobuttonshow might have mediashows as entries rather than
single tracks
Multi-level menus
Subshows can be nested to any depth; the limit is probably the confusion that it will
cause the audience when using them. Subshows are tracks so appear in the
medialist as Show tracks.
Child tracks are tracks used in a special way by mediashows and liveshows. If a child
track is specified in the profile it can be initiated while running any track in the parent
show returning to the next track in the parent when finished. Child tracks, like any
track can be a show and are sometimes referred to as Child Shows..
The Egg Timer
In all shows transitions between tracks are gapless (no black gaps between tracks).
This is achieved by freezing videos and images at the end of the track while the next
Page 20
Version 1.3.5a, 1 May 2018
track is loaded. For manual operation this means there is a delay of up to 2 seconds
after a control is pressed. The ‘Egg Timer’ can be used cover this delay by displaying
text while the loading takes place. The text appears above the track display so its
content, format, and position is configurable in the show profile.
Concurrent Shows
Pi Presents can run two or more shows concurrently, see Section 8.4. The
concurrent shows appear to run in parallel. This has many uses which include:
Providing a background audio track to a slideshow.
Use two mediashows, one with the slideshow and the other with the audio
tracks. The latter will need the controls disabled if there is customer
interaction with the former.
Dividing the screen into areas (Show Canvases) each showing a different
Show. Perhaps an automatic slideshow in one area, time of day provided by a
show with a track plugin in another, and a user controlled menu of pictures in
a third. Controls may need to be disabled for all but one of the shows. For
more advanced applications Pi Presents can be configured so that each
concurrent show and each subshow has their own sets of controls.
Being really thrifty and doing two completely different tasks with the same Pi,
perhaps a slideshow in the Reception and a dummy talking in a museum
exhibit triggered by a PIR
Each concurrent show can have subshows.
5.2 Shows
Shows have fields which control the sequencing and look of the show. They also
have a number of fields which provide default values for all the tracks in the show
e.g. Duration, Transition, OMXPlayer Audio; tracks will use the values in the show if
their corresponding fields are left blank.
All shows have the following fields:
Title - Text displayed in the editor and in the entries of a menu show
Show Reference - A label which allows other shows to reference this show.
Can be any alpha-numeric string without spaces.
Medialist - this is the name of a file which appears in the medialist panel. It
must have the extension .json. Every show must have a medialist to define
the tracks in the show. The same medialist can be used by more than one
show.
5.2.1 Mediashow and Artmediashow
Think of a mediashow as a slideshow that can play tracks of different types - videos,
audio tracks, images, and even animation control sequences.
Page 21
Version 1.3.5a, 1 May 2018
Mediashows have a number of fields to define the control of the show, e.g. Trigger
for Start, Repeat/Single and Sequence.
A track can be associated with a mediashow such that the track is accessible from
any track in the show. These are termed 'child tracks'. The Child Track parameter
specifies the track reference of the child track, which may be a track or a show.
Associated with the use of a Child Track is ‘Hint Text’ that is displayed only when the
Child Track field is not blank.
The Repeat/Single field control how mediashows run:
repeat - the mediashow repeats until it is stopped.
single-run - the mediashow runs once and then exits. Single run is primarily
for use in subshows and with Show Control
Other fields allow mediashows to the customised for many applications. The table
below shows the Trigger and other field settings for common uses of mediashows
and liveshows.
Task
Repeat
Trigger for
Start
Trigger for
End
Continuous show
repeat
Continuous show that repeats repeat
the medialist until a period of
time has elapsed, then it
ends.
Continuous show that repeats repeat
the medialist at intervals
start
start
none
none
start
none
Run a medialist triggered by
an input (was single shot)
Run a medialist triggered by
an input. Inhibit re-triggering
for a period of time after the
medialist completes.
Play a track triggered by an
input. If sequence = shuffle a
random track will be played
each time.
Start and stop playing a
medialist when an input is
pressed and released
repeat
input
none
repeat
input
none
repeat
input
repeat
input
Other
Fields
(where
non-zero)
Show
Timeout =
h:m:s
Repeat
Interval =
h:m:s
Repeat
Interval =
h:m:s
Track
Count Limit
= tracks
input
In gpio.cfg
use rising
edge and
falling
edge of a
pin for the
two
triggers.
Page 22
Version 1.3.5a, 1 May 2018
‘Magic Picture’. Start a video
and pause it after its first
frame. Unpause using the go
command and then repeat.
repeat
start
none
Use a mediashow as a
subshow or as an item of a
menu, radiobuttonshow etc.
single-run
start
none
Video
requires
‘freeze at
start’ and
‘after first
frame’.
Also the go
command
to be used
Mediashows and Liveshows can also be controlled by the user using Commands
such as Up, Down and Stop. The association of these with the Symbolic names of
Input Events is in the Controls field.
Artmediashow
Artmediashows provide full gapless playback; there is no gap between tracks and
tracks do not freeze at their end to cover loading of the next track. Artmediashows
have some limitations and do not have the fields and commands which are shown in
brackets in the Table below:
Subshows
Child Tracks
Start, Next and End Triggers.
Web Tracks
5.2.1.1 Controls and Commands
The first means of controlling mediashows and liveshows is by using their
Commands. Out of the box these Commands are bound to a set of symbolic names
and these in turn are bound to a set of keyboard keys. In addition control of Pi
Presents by GPO with a useful set of bindings can be enabled easily by copying a
prepared gpio.cfg file to a profile from /pipresents/pp_resources/pp_templates:
The out of the box settings are:
'Out of the box'
Effect
For GPIO Pin see Section 14.2.1
Command
up
Symbolic
Name
pp-up
down
pp-down
Cursor
Down
play
pp-play
Return
pause
pp-pause
Spacebar
pause-on
Key
Cursor Up
GPIO Pin.
Previous track in mediashow or
liveshow, or up for menu
Next track in mediashow or
liveshow, or down for menu
Start an entry in a menu, or start
a child show.
toggle pause for tracks that
support pause.
pause for tracks that support
pause.
Page 23
Version 1.3.5a, 1 May 2018
pause-off
mute
unmute
stop
pp-stop
Escape
(go)
exit
pp-exit
omx-*
null
mplay-*
(uzbl-*)
unpause for tracks that support
pause.
mute for tracks that support
mute.
unmute for tracks that support
mute.
Stop playing a track and, if a
show is in its quiescent state and
is not a top level show, return to
the parent show.
Quiescent state:
Liveshow/Mediashow –
at all times
Menu – displaying menu.
If it is in its quiescent state and a
top level show then stop closes a
single-run show but moves to the
next track for a repeating show.
unpause a video track that is
‘frozen at start’
inhibits the control with the same
symbolic name that has been
defined in the show.
Stop playing a track and exit to
the parent show or, if a top level
show, close the show.
execute a runtime commandl for
the video player (Section 10)
execute a runtime command for
the audio player (Section 10)
execute a runtime command for
the web browser (Section 10)
The 'out of the box' key for each operation is set in /pipresents/pp_io_config/keys.cfg
and the GPIO pin in gpio.cfg. The bindings can be modified as described in Section
14.2. The binding of the Command to the symbolic name is specified in the Controls
field of the show. It is unlikely you will want to modify these but you may wish to
override them for an individual show as described below.
Remember that if more than one show is running concurrently the input event is
passed to and potentially executed by each concurrent show. This may be
undesirable, for example if a mediashow of audio tracks is running as a background
to a manually advanced slideshow; we do not want the up and down operations to
change audio track, so Disable Controls is used with the audio show.
If Disable Controls = yes for the show then all Commands are disabled for the show
and it must run automatically or be controlled by triggers as described in the next
section. For more advanced situations individual Commands can be deleted or
bound to alternative symbolic names for a specific show by using the Controls field of
a show.
Commands can be placed in the Controls field of the tracks in addition to the
Controls field of the mediashow. The controls in a track are merged with and override
those in the show. This is generally not required but could be used where, for
example it is required that the audience watches the whole of a video. In this case
using the null commands would inhibit up/down/stop for the track
Page 24
Version 1.3.5a, 1 May 2018
5.2.1.2 Triggers
Mediashows and liveshows have triggering facilities. The facilities are designed for
use when the show is played without the full user interaction provided by their
Commands
Immediately after a mediashow is run, or it repeats, the show uses the Trigger For
Start field to decide what to do next, After each track Trigger For Next can be
employed to control movement to the next track. Trigger for End determines when
the mediashow finishes
Triggers can be applied to sub-shows and child shows. Triggers are not inhibited by
‘Disable Controls’.
5.2.1.2.1
Trigger for Start
Trigger For Start can take the following values:
start
The mediashow continues to the first track.
input /input-persist
The mediashow waits for an input event before running the first track of the
show. The symbolic name of the input event must be included in the Trigger
for Start Parameter field. Input-persist is a way of implementing ‘magic
pictures’ now replaced by the better Freeze at Start, After First Frame in a
video track.
Text to display while waiting for a Star Trigger is in the Notices Tab of a
mediashow or liveshow.
5.2.1.2.2
Trigger for End
Trigger for End causes the show to exit (single-run) or repeat (repeat). It can take the
following values:
none
The end trigger is not operative the show will exit or repeat at the end of the
medialist/live tracks directory.
input – the end trigger is generated when an input with a symbolic name
matches that in the Trigger for End Parameter field.
5.2.1.2.3
Trigger for Next
The Trigger For Next field allows individual tracks in a mediashow to be triggered by
an input event:
Page 25
Version 1.3.5a, 1 May 2018
None - The trigger is not operative the show will continue to the next track at
the end of the previous.
Input - The show moves to the next track when it is triggered by the input
event having the symbolic name specified in Trigger for Next Parameter field.
The track duration can be used to set a longstop on the trigger, or if set to 0 to
allow forward movement by trigger only.
5.2.1.3 Fields
Fields for Mediashow and Liveshow. Fields not used for Artmediashow and
Artliveshow in brackets
Field
Show Tab
Type
Title
Show
Reference
Medialist
Examples
(art)mediasho
w
My First Show
show1
show1.json
(Trigger For
Start)
start
(Trigger for
Start
Parameter)
PIR
(Trigger for
Next)
continue
(Trigger for
Next
Parameter)
Values
Cannot be edited
Text describing the show. Displayed in the editor
and on menus
A ‘label’ by which the show is referenced by
other shows. Any text without spaces
Filename of the medialist file containing the
tracks for the mediashow. By default it is the
same as the Show Reference but can be
changed.
How the media show proceeds after it is started
and at the beginning of a repeat:
start - continue without waiting
input - wait for an input event.
input-persist – wait for an input event.
Input-persist displays the immediately
previous track while waiting (providing
videos are frozen at their end)
If Trigger For Start is 'input', or ‘input-persist’:
A symbolic name that is bound to an
input event as described in Section 14.2
How to trigger the next track
input - respond an input event
continue – continue without waiting
Input can be used in one of two ways:
If the duration of a track is zero the mediashow
will move forward only when the trigger is
received.
If the duration of a track is non-zero then the
mediashow will move forward automatically and
also when the trigger is received.
If Trigger For Next is 'input':
A symbolic name that is bound to an
input event as described in Section 14.2
Page 26
Version 1.3.5a, 1 May 2018
Field
Sequence
Repeat/Single
Examples
repeat
Values
sequence of tracks:
ordered - played in the order of the
medialist
shuffle - play tracks in a random order.
For liveshow this is a true shuffle so a
track will not be replayed until all the
tracks in the live tracks directories have
been played. For mediashow the next
track is chosen randomly.
How the media show is repeated:
repeat – Wait for Trigger for Start. Tracks
in the medialist are then played once and
then the medialist repeats by waiting for
Trigger for Start.
single-run – Waits for Trigger for Start.
Tracks are then played once and then the
show closes.
Note: There is no natural end to a shuffled set of
tracks.
How the end of a show can be triggered. See the
table above for more detail.
none – the end trigger is not operative
input – Ends after an input event as
described in Section 14.2
duration – end the show after a period of
time.
(Trigger For
End)
none
(Trigger for End
Parameter)
5:00
If Trigger For End =:
input – A symbolic name that is bound to an
input event as described in Section 14.2
(Track Count
Limit)
1
(Repeat
Interval)
30
If non-zero the show closes or repeats after
Count tracks have been played. Intended fo use
where the Track Count Limit is less than the
number of anonymous tracks in the medialist.
h:m:s
The show repeats/ends at Repeat Interval or at
the end of the medialist, whichever is last. If the
medialist ends before Repeat Interval then a
blank screen is displayed.
Interval = 0 always repeats/ends when medialist
is complete. Repeat Interval=0 does not work for
shuffle as a shuffled medialist never finishes.
For shuffle and Repeat Interval>0 the show
always continues until Repeat Interval as a
shuffled medialist does not finish
Page 27
Version 1.3.5a, 1 May 2018
Field
(Show Timeout)
Examples
1:30:20
Show Canvas
100 100 400
600
Values
h:m:s If non-zero end the show after the
specified period if nothing else has ended it.
The top left and bottom right coordinates of the
show canvas. Show canvas helps the user divide
the screen when displaying more than one
concurrent show. If the field is not blank the
Show Canvas dimensions controls the placing
and size of images and videos taking the place
of the dimensions of the screen. The Show
Canvas determines the origin of the images (top
left) however it is not a window and does not
crop the image or video so, if the bottom right coordinates of the image are larger than the Show
Canvas it can overlap other show canvases.
Instead of 2 x,y, pairs x1+y1+w*h can be used
Child Track
Tab
(Child Track)
(Hint Text)
(Hint Font)
child-track
Press Play to..
Helvetica 30
bold
Non-blank to enable a Child Track and to specify
the track reference of the track.
A single line of text
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
(Hint Colour)
white
(Hint Justify)
(Hint x)
right
500
(Hint y)
900
Eggtimer Tab
EggTimer Text
Eggtimer Text
Font
Loading….
Helvetica 30
bold
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
left, right, center – Justify lines in a block of text
Position of left of text. If blank then the text is
centred on the show canvas
Position of top of text. If blank then the text is
centred on the show canvas
Eggtimer text is displayed when the next track is
being loaded
A single line of text
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Page 28
Version 1.3.5a, 1 May 2018
Field
Eggtimer Text
Colour
Examples
white
Values
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
Eggtimer Text x
Position
100
Eggtimer Text y
Position
100
Eggtimer Justify
right
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
left, right, center – Justify lines in a block of text
Waiting…
Text to show when Waiting for Trigger
Notices Tab
(Trigger Wait
Text)
Notice Text x
Position
distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
Notice Text y
position
Notice Text
Colour
Notice Text
Font
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Font Chooser to select a font, or type
one in:
Notice Justify
right
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
left, right, center – Justify lines in a block of text
Show
Background
and Text Tab
Background
Image
+/media/image
.jpg
If not blank the file name of an image which is
used as the background for any tracks in the
show. The image is warped to fit the Show
Canvas. If you do not want background images
to be warped then edit them in advance to be the
size of the Show Canvas.
Page 29
Version 1.3.5a, 1 May 2018
Field
Background
Colour
Show Text
Show Text Font
Show Text
Colour
Examples
Pictures from
my holiday
Helvetica 30
bold
white
Show Text x
Position
100
Show Text y
Position
100
Show Text
Justify
right
Track Defaults
Tab
Duration
10
Pause Timeout
5
Track Text Font
Helvetica 30
bold
Track Text
Colour
white
Values
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
The background colour is set to black when Pi
Presents starts. The value in this field is used by
a track in the show if the value in the track’s field
is blank.
If the resulting Background Colour is blank the
background colour is not changed.
Show text is overlayed on all tracks in the show.
If not blank the text to be displayed.
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
left, right, center – Justify lines in a block of text
Tracks played in the show need some
configuration if not supplied in the individual
tracks
seconds. How long a track having no natural end
is displayed. A value of 0 displays continuously.
seconds. If not blank and greater than 0 a
paused track will automatically unpause after the
timeout.
Use the Font Chooser to select a font, or type
one in.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widget-
Page 30
Version 1.3.5a, 1 May 2018
Field
Examples
Track Text x
Position
100
Track Text y
Position
100
Track Text
Justify
Transition
right
cut
Image Rotation
Image Window
90
original 10 100
Values
styling.htm
distance of the left end of the text from the left of
the screen (pixels) If blank then the text is
centred on the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred
on the show canvas
left, right, center - Justify lines in a block of text
cut. Type of transition between tracks.
Currently not used.
Rotates the image
For any image track in the show a viewport in
which to show the image. See section 5.4.4.1
fit
fit 1010 40 40
Video Audio
Video Audio
Volume
Video Window
fit ANTIALIAS
hdmi
0
original
hdmi/local/both/alsa . Sound output
channel for any video track played by omxplayer
from the show. If blank then the channel is set
automatically by the presence of a hdmi monitor.
(can be forced in raspi-config) (both is
hdmi+local)
Volume of audio for the video track (-60 -> 0 dB).
For any video track in the show a viewport in
which to show the video.
warp
original – use OMXPlayer default
behaviour
warp – scale to the size of the screen
without maintaining aspect ration
warp 10 100
200 700
warp followed by two x,y, pairs (top left,
bottom right) – the viewport window. The
video is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used
Freeze a video at the start of the track
no – no freeze
before-first-frame – the video is paused
before the first frame is shown
after-first-frame - the video is paused
after the first frame is shown
To continue after the freeze use the ‘go’
command.
Freeze at Start
before-firstframe
Audio tracks can be ‘frozen at start’ by playing
Page 31
Version 1.3.5a, 1 May 2018
Field
Freeze at End
Video Player
Options
Audio Player
Audio
Audio Player
Speaker
Audio Player
Volume
Audio Player
Options
(Web Window)
Examples
yes
local
stereo
0
warp
warp 10 100
200 700
Controls Tab
Controls
pp-play play
pp-up up
Values
them as video tracks.
yes/no If yes the video will be frozen near the
last frame until the next track is ready to be
displayed.
Other options for omxplayer (care required to
avoid have a nice day!)
hdmi/local. Sound output channel for any audio
track played by MPlayer from the show.
left/right/stereo. Speaker for any audio track
played by MPlayer in the show.
Volume of audio track (-60 -> 0dB) played by
MPlayer in the show.
Other options for MPlayer (care required to avoid
rejection!)
For any web track in the show a viewport in
which to show the web page.
warp - scale to the size of the screen
without maintaining aspect ration
warp followed by two x,y, pairs (top left,
bottom right) - the viewport window. The
web page is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used
Defines the bindings between symbolic names of
input events and commands
See Table above and Section 6.4
One binding per line each with the format:
symbolic-name command
Disable
Controls
Show Control
Tab
Show Control at
Beginning
Show Control at
End
no
Bindings are NOT inherited by subshows.
yes/no
If 'yes' Commands (e.g. play, pause, up, down,
stop) are disabled. This is a quick way to inhibit
all controls for a concurrent show. For more
selective control use the Controls field
open audio1
See Section 8.2
close audio1
See Section 8.2
Page 32
Version 1.3.5a, 1 May 2018
5.2.2 Menu
A menu show uses the Title and Thumbnail fields of tracks and of shows to
automatically generate a menu on the screen. The Up and Down Commands can
then be used to scroll the menu and the Play Command to play the track or show.
A menushow needs an associated menu track in its medialist which defines the
layout of the menu:
Display, thumbnails, bullets or Titles in many combinations
Align the menu vertically or horizontally
Create multi-column, multi-row menus
Alter the separation, colours and font of the menu items
5.2.2.1 Controls and Commands
Menu Commands are the same as those for Mediashow and are described in details
in Section 5.2.1.1
5.2.2.2 Fields
Field
Show Tab
Type
Title
Show
Reference
Show Canvas
Medialist
Examples
menu
mymenu
Show Timeout
mymenu.json
59
Track Timeout
20
Menu Track
menu-track
Values
Essential information
Cannot be edited
Text describing the show, displayed in the editor.
A ‘label’ by which the show is referenced by other
shows. Any text without spaces
See Mediashow
Filename of the medialist file containing the tracks
for the menu.
h:m:s, If there is no activity on the menu Pi
presents automatically close the show. 0 for no
timeout.
h:m:s, If non-zero tracks launched from the menu
will be stopped after this time and control will
return to the menu.
The track reference of the track that will display the
menu content. Must be of type Menu Track
Eggtimer Tab
Eggtimer text is displayed when the next track is
being loaded.
See mediashow
Show
Background
and Text Tab
Show text is overlaid on all tracks other than
message tracks opened from the menu.
Page 33
Version 1.3.5a, 1 May 2018
Field
Examples
Values
See mediashow
Track Defaults
Tab
pp-down down
Controls Tab
Tracks played from a menu need some
configuration if not supplied in the individual
tracks
See Mediashow
Defines the bindings between symbolic names of
input events and commands
One binding per line each with the format:
symbolic-name command
Bindings are not inherited by subshows.
Disable
Controls
no
See Table above and Section 5.2.1.1
yes/no
If 'yes' the commands are disabled. This is a
quick way to inhibit all controls for a concurrent
show. For more selective control use the
Controls field
Show Control
Tab
See Mediashow
5.2.3 Liveshow and Artliveshow
A Liveshow is identical to a Mediashow except that the content is dynamically
supplied from directories of media, the Live Tracks directories, and is therefore
limited to video, image, and audio tracks, and their track plugins. The tracks from the
two directories are merged and, if sequence = ordered, sorted by the leaf of the file
name.
See Section 5.2.1 for details of commands, triggers and fields.
A medialist must be associated with a Liveshow. It is used for the Child Track, List
Empty Track, and Escape Track all other tracks in it will be ignored.
Actions on the list of tracks being empty:
a. List Empty/Escape
If the liveshow’s repeat field is ‘Single Run’ then the liveshow exits.
If the liveshow’s repeat field is ‘Repeat‘ and List Empty Track’ is blank then an
error will be generated.
If the liveshow’s repeat field is ‘Repeat’ and the ‘List Empty Track’ is not a
show it is run whenever the list of tracks to be played is empty. The track is
played once and then the content of the list of tracks is re-evaluated.
Page 34
Version 1.3.5a, 1 May 2018
The List Empty Track may be a show. If so the show should be ‘single run’ or
there should be some other method of exiting from the show so that the list of
liveshow tracks can be re-evaluated. If the list is then empty the Escape track
is run once. This track must not be a show. Its purpose is to allow the
liveshow to be stopped or exited if it is a subshow of another show.
The limitation of this method is that the empty track/show uses the same
Show Canvas as the liveshow.
b. Show Control
The ‘Show Control on Empty’ and ‘Show Control on Not Empty’ fields allow
other shows to be opened or closed depending on whether there are tracks to
be played.
It is unlikely that both methods will be required in the same application.
Artliveshow
Artliveshows provide full gapless playback; there is no gap between tracks and tracks
do not freeze at their end to cover loading of the next track. Artliveshows have some
limitations and do not have the fields which are shown in brackets in the Table in
Section 5.2.1.3:
Start, Next and End Triggers.
Child Tracks
The Liveshow has the following fields additional to those of the Mediashow:
Field
Live Tracks
Directory 1
Examples
Live Tracks
Directory 2
(List Empty
Track)
(Escape Track)
Show Control
Tab
Show Control
on Empty
Show Control
on Not Empty
Values
The full path of a Directory containing tracks for
this show. If blank the tracks are taken from the
pp_live_tracks directory in pp_home
The full path of a Directory containing tracks for
this show. If blank the tracks are taken from
directory specified in the –l command line option.
Not ArtLiveshow. Run when the list of tracks in a
liveshow is empty. See text
Not ArtLiveshow. Run when returning from an
Empty Track which is a show. See text.
open show1
See Section 8.2
close show1
See Section 8.2
5.2.4 Radiobuttonshow
A Radiobuttonshow provides the sort of show facilities that are in many kiosks
namely:
'Start with an initial display which might include some text inviting the user to
press buttons or touch the screen to initiate a track. While playing the track
Page 35
Version 1.3.5a, 1 May 2018
pressing another button will play another track. At the end of a track or when
Stop is pressed revert to the initial display.'
In Pi Presents the initial display can be an image, message, video or audio track, or a
show. Playing of other tracks is by means of commands in the Controls field of the
Radiobuttonshow e.g.
but1 play myimagetrack
but2 play myvideotrack
5.2.4.1 Controls and Commands
Each control has three fields separated by spaces:
symbolic name - the symbolic name of the input event that will play the show
or track.
command – see below
track - the Track Reference or Show Reference of the track or Show to be
played.
Command
play
return
stop
Argument
track-ref
go
unpause a video track that is ‘frozen at start’
exit
null
pause
pause-on
pause-off
mute
unmute
omx-*
close the Radiobuttonshow
inhibits the control with the same symbolic name
that has been defined in the show.
toggle pause on video, audio, or image tracks
pause for tracks that support pause
unpause for tracks that support pause
mute for tracks that support mute
unmute for tracks that support mute
execute a runtime control for the video player
Play the track specified by track-ref
return to the first track of the show
stop the current track and, if show is the quiescent
state and this is not a top level show, then close
the show.
The quiescent state is when the first track is
showing.
(Section 10)
mplay-*
execute a runtime control for the audio player
uzbl-*
execute a runtime control for the web browser
(Section 10)
(Section 10)
Commands can be placed in the Controls field of the tracks in addition to the
Controls field of the radiobuttonshow. The controls in a track are merged with and
override those in the show. This is generally not required but could be used where,
for example it is required that the audience watches the whole of a video. In this case
using the null command would inhibit the symbolic names that play other tracks or
stop the track.
5.2.4.2 Fields
Page 36
Version 1.3.5a, 1 May 2018
Field
Show Tab
Type
Title
Examples
radiobuttonshow
My Show
Show
Reference
Show
Canvas
Medialist
myradioshow
First Track
myfirsttrack
Show
Timeout
1:59
Track
Timeout
20
Controls in
Subshows
no
mymedia.json
Values
Cannot be edited
Text describing the show displayed in the Editor
and menu
A ‘label’ by which the show is referenced by
other shows. Any text without spaces
See Mediashow
Filename of the medialist file containing the
tracks for the Radiobuttonshow. All tracks should
have a Track Reference.
The Track Reference of the track that will form
the initial display for the show.
h:m:s, If there is no activity on the First Track Pi
Presents automatically returns to the previous
show. 0 for no timeout.
h:m:s If non-zero tracks launched from the
radiobuttonshow will be stopped after this time
and control will return to the show.
yes/no
If no (normal Radiobuttonshow operation )
pressing a button or key while a track is playing
will start playing the selected track.
If yes and the track is a show then input events
will be passed down to the show. This allows the
show to be controlled but it will not be possible to
select another track while a track is playing.
Eggtimer
Tab
See Mediashow
Show
Background
and Text
See Mediashow
Track
Defaults
Tab
See mediashow
Controls
Tab
Page 37
Version 1.3.5a, 1 May 2018
Field
Controls
Examples
myname play
mytrack
Values
Defines the bindings between symbolic names of
input events and commands
One binding per line each with the format:
symbolic-name command [arg]
Bindings are NOT inherited by subshows.
Disable
Controls
no
See Table above for list of commands
yes/no
If 'yes' all Commands are disabled. This is a
quick way to inhibit all controls for a concurrent
show. For more selective control use the
Controls field.
Show
Control Tab
See
Mediashow
5.2.5 Hyperlinkshow
A Hyperlinkshow provides the type of show facilities that are used in touchscreen
displays in museums:
'Start with an initial page with some introductory text, video or image and a
selection of on screen buttons which allow the user to move to another page.
Each page can have a different selection of buttons to link to other pages.
When in any page other than the initial page additional buttons allow the user
to go back to the previous page or to return to the initial page.
All of the touchscreen displays that I have tried in my researches seem to work this
way, or are Radiobuttonshows.
Every page in the example above is a track in a Hyperlinkshow. Each has a Controls
field which contains commands implementing the movement between tracks and
back.
e.g.track ‘story1b’ might contain the following controls:
next-name call story1c
alternative-name call alternative1
back-name return
home-name home
xxx-name is the symbolic name of an input event. This example says either go
forward to ‘story1c’ or to ‘alternative1’, return to the previous track (which was
probably ‘story1a’), or return to the home track which probably means going back
through ‘story1a’ without displaying it.
Page 38
Version 1.3.5a, 1 May 2018
When executing the call command Pi Presents remembers where it has come from in
the ‘path’ (essentially a stack) so the return command can go back one removing the
current track from the path. Think of nested call and return of subroutines in a
programming language.
There is a special track called the Home Track. The home command can skip back
along the path until it arrives at the Home Track so it is not necessary to know how
far you have gone to get back to a known starting point.
Each control has three fields separated by spaces:
symbolic name - the symbolic name of the input event that will trigger the
command
command - call, return, goto, jump, exit, null, repeat, pause, no-command,
and runtime controls
track - the Track Reference of the track to be played
5.2.5.1 Controls and Commands
Command
call
Effect
play Track Reference and add it to the path
return
Argument
Track
Reference
return
number
return n tracks back up the path removing the
track from the path, stops at Home Track.
return
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
Page Count : 111
Producer : Nitro PDF PrimoPDF
Create Date : 2018:05:01 19:58:40-01:00
Modify Date : 2018:05:01 19:58:40-01:00
Title : Microsoft Word - manual_1p3p5a.doc
Creator : PrimoPDF http://www.primopdf.com
Author : Ken
EXIF Metadata provided by EXIF.tools