v1.0.0 beta 1

.cfg-dist/categories.tsv

@@ -0,0 +1,4 @@
+intro	Introduction
+lastshop	Last Shop
+items	Items
+closing	Closing

.cfg-dist/loading.tsv

@@ -0,0 +1,2 @@
+1	Just a minute
+2	I'm looking up fruit and vegetables

.cfg-dist/log.tsv

@@ -0,0 +1,2 @@
+1	Participant coughs
+2	Participant laughs

.cfg-dist/messages.tsv

@@ -0,0 +1,26 @@
+h1	intro	Hello	Hello, my name is Gerry and thank you for coming in today. 
+h2	intro	What's your name	What’s your name?
+h3	intro	Great them	Great! Nice to meet you, [name*]!
+h4	intro	Introduce study	For this study, I want to know about the sorts of fresh fruit and vegetables you buy, and how you describe them.
+h5	intro	About the information they provide	The information you tell me will be used to understand more about how people pick and choose their fruit and vegetables.
+h6	intro	Question if it makes sense	Does this make sense? 
+ls1	lastshop	Last time you bought	So, first of all, tell me about the last time you bought some fresh fruit or vegetables. When was it?
+ls2	lastshop	What did you buy?	What did you buy?
+i1	items	How did you buy?	How many did you buy?
+i2	items	Why did you buy?	Why did you buy them?
+i3	items	Loose or multipack?	Do you prefer to pick loose [name*] or a multipack of them?
+i4	items	Buy often?	Do you buy them often?
+i5	items	Always buy the same number?	Do you always buy the same number of [name*]?
+i6	items	Supermarket or greengrocer?	Do buy them in the supermarket or a green grocer?
+i7	items	Weekly shop?	Is that while you do your weekly shop?
+i8	items	How you chose some?	Can you describe how you chose [name*]?
+i9	items	Handle before picking up?	Did you handle them before picking it up?
+i10	items	Different varieties?	Did you look at different varieties?
+i11	items	What's good? Describe it.	What’s a good [name]? Describe it for me.
+i12	items	Size?	Is bigger better, or smaller?
+i13	items	What colour?	What about the colour? 
+i14	items	Why do you prefer characteristic? 	Why do you prefer [characteristic]?
+i15	items	Do you smell/feel?	Do you smell them or feel their texture?
+i16	items	Feel good?	Tell me what makes a [name] feel good?
+i17	items	Different smell?	Is there a different in smell?
+c1	closing	Goodbye	Great! Goodbye [name$].

.cfg-dist/settings.cfg

@@ -0,0 +1,115 @@
+
+
+
+[MVUI]
+
+# Title of the Mobile VUI window
+window_title: Gerry, the Green Grocer
+
+# VUI UI
+background_colour: #000000
+
+# VUI UI text decoration
+typeface: Helvetica
+font_size: 32
+text_colour: #ffffff
+
+# Initial text on the Mobile VUI window
+initial_text: Welcome to Gerry, the Virtual Green Grocer<br><br>Please wait a moment...
+
+; Size of the orb itself
+orb_size: 120
+
+; Maximum size of the animations around the orb, including the orb
+orb_size_max: 240
+
+; Enable fluttering when listening (uses a mic input)
+orb_enable_flutter: True
+
+; Size of the orb's border
+orb_width: 10
+
+; Colour of the orb when the VUI is resting
+orb_nothing: #223247
+
+; Colour of the orb when the VUI is listening
+orb_listening: #513469
+
+; Colour of the orb when the VUI is computing
+orb_computing: #e1e1e1
+
+; Colour of the orb when the VUI is speaking
+orb_speaking: #AB3F7D
+
+; Colour of the orb flutter
+orb_flutter_colour: #49515C
+
+
+
+[ActiveMQ]
+
+# ActiveMQ/STOMP server
+host: localhost
+
+# ActiveMQ/STOMP port
+port: 61613
+
+# ActiveMQ/STOMP username
+username: admin
+
+# ActiveMQ/STOMP password
+password: password
+
+# ActiveMQ/STOMP queue where NottReal will listen for status updates
+nottreal_queue: /queue/nottreal
+
+# ActiveMQ/STOMP queue where the Wizard's messages will be sent
+destination_queue: /queue/voicesynth
+
+# ActiveMQ/STOMP message format
+message_text: message: %%s
+
+# Message sent to interrupt any output
+message_interrupt: interrupt
+
+# Default format for messages about on the state NottReal should be in
+message_state: state: %%s
+
+# String for the nothing state messages sent to NottReal (substituted into message_text)
+message_state_nothing: nothing
+
+# String for the speaking state messages sent to NottReal (substituted into message_text)
+message_state_speaking: speaking
+
+# String for the listening state messages sent to NottReal (substituted into message_text)
+message_state_listening: listening
+
+# String for the computing state messages sent to NottReal (substituted into message_text)
+message_state_computing: computing
+
+
+
+[VoiceCerevoice]
+
+#  Command to speak something (e.g. ./run_aria_tts.sh on macoS/Linux, run_arias_tts.bat on Windows)
+command_speak: ./run_aria_tts.sh "%%s"
+
+# Interrupt command (e.g. pkill -f run_arias_tts.sh on macOS/Linux, taskkill /F /IM run_arias_tts.bat on Windows)
+command_interrupt: pkill -f run_arias_tts.sh
+
+
+
+[VoiceMacOS]
+
+# Options for the macOS voice
+command_options: -vserena
+
+
+
+[VoiceShellCmd]
+
+# Command to speak something
+command_speak: say "%%s"
+
+# Command to cancel current voice output
+command_interrupt: killall say

.gitignore

@@ -0,0 +1,111 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# NottReal 
+.DS_Store
+*/.DS_Store
+cerevoice/
+data/
+cfg/

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Martin Porcheron and Mixed Reality Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,86 @@
+<h1 align="center">
+	NottReal
+</h1>
+
+A Python application for running Wizard of Oz studies with a voice-based  user interface.
+
+## Dependencies
+NottReal requires Python 3 and some dependencies, run `pip3` in the root directory:
+
+	 pip install -r requirements.tx
+
+## Running
+Run the code by calling `python3 nottreal.py`, with the various options accessible with `-h` option. Summarily:
+
+* Logging is controlled by using the `-l` option, with the levels `WARNING`, `DEBUG`, `ERROR`, `INFO`, `CRITICAL`
+
+* The configuration directory can be set using the `-c` option. A sample configuration directory is in `.cfg-dist`. Create a copy of this directory and use the option to specify the location.
+
+  If you put your configuration in a directory called `cfg`, you do not need to set this option. 
+
+* NottReal can log all 'spoken' output to TSB files in a specified directory, where a file is created each time the application is run. Point NottReal to this directory with the `-d` option.
+
+* Multiple voices are supported and can be set using the `-v` option followed by the chosen system. Built in choices are `ShellCmd`, `macOS`, `activeMQ`, `cerevoice`, and `outputToLog` (most have configuration in `settings.cfg`). 
+
+* Multiple output windows are supported, although only `MVUIWindow` is implemented. This window  looks a bit like a Mobile VUI). Set this to open automatically with the `-o` option, e.g.` -oMVUIWindow`.
+
+
+
+## App layout and configuration
+Copy the contents of the `.cfg_dist` directory to a new directory (e.g. `cfg`).  The application doesn't load configuration files from `cfg_dist`---these are only accessed if no configuration is specified.
+
+In summary, the NottReal *Wizard Window* UI has the following features:
+	a) A *textbox* to type messages to send to participant
+	b) A list of queued *messages*
+	c) A list of previously sent *messages*
+	d) A list of categories of *prepared messages*
+	e) A list of *prepared messages*
+	f) A list of previously filled *slots*
+	g) A list of optional *log-only messages*
+	h) A list of *loading messages* to display on the Wizard window
+	g) A list of options, dependant upon the voice used
+
+NottReal can store all sent messages in a timestamped log. You can configure this by passing in a directory's path to the `-d` option.
+
+There is a fake mobile voice user interface view that can be enabled from the menu (or opened by default using the `-w` option). The configuration for this is in the `settings.cfg` file.
+
+In more detail, the application includes a *textbox* to type messages to send to the participant. If a previous message is being spoken when another message is sent, it will be queued up. Previously uttered/delivered messages are displayed at the bottom of the UI.
+
+NottReal also includes *prepared messages* that can be quickly sent to the participant through the simulated voice. These messages are categorised and presented as tabs in the UI. The categories can be configured in the file `categorises.tsv` in the configuration directory and consist of a unique category ID and the label in a tab-separated format:
+
+	unique_cat_1	Category 1
+	unique_cat_2	Category 1
+	unique_cat_3	Category 1
+	unique_cat_4	Category 1
+
+You must have at least once category, thus if you do not wish to use this feature, simply leave a placeholder category in `cfg/categorises.tsv`, e.g.:
+
+	category	Prepared messages
+
+Prepared messages are words that will be sent to the voice simulator on being double clicked. They are defined in `messages.tsv` in the configuration directory as a unique message ID, a category ID, a title and the text:
+
+	unique_message_1	unique_cat_1	Title	Prepared message to be sent to the participant 
+
+Prepared messages can also contain *slots*, which are segments of text to be replaced at run-time by the Wizard. For example, part of a message may include words uttered by a participant. Slots are defined as a name within square brackets:
+
+	unique_message_2	unique_cat_1	Title 2	Prepared message to be sent to the participant with a [slot]
+
+When you double click a message with a slot, the UI will place the message in the *textbox* and automatically highlight it so that it can be edited quickly. Subsituted slot values are displayed in the UI also. If there are multiple slots, pressing either the `enter` or `tab` key will move to the next slot. Press `ctrl` + `enter` will send a message if there are no slots left.
+
+Slots can use a previously substituted value automatically using the asterisk at the end of its name:
+
+	unique_message_3	unique_cat_1	Title 3	Prepared message to be sent to the participant with a [slot*]
+
+On the first use of this message, the Wizard will have to type a value for the slot. On successive double-clicks of this message, NottReal will automatically substitue the value. There is an option to reset this tracking on a category change. Alternatively, if a particular should cancel tracking for that particular slot, it can use a dollar at the end of its name:
+
+	unique_message_4	unique_cat_1	Title 4	Prepared message to be sent to the participant with a [slot$]
+
+The window also includes a dropdown list of messages to be sent to the voice simulator. These automatically show the loading animation during and after being sent. They are specified in `loading.tsv`, consisting of a unique ID and the message:
+
+	unique_loading_message_1	Message text
+
+The window contains messages that can be added to the log data only (e.g. if you wanted to record certain events occuring without simulating a voice):
+
+	unique_log_message_1	Log message
+
+Finally, to interrupt the currently delivered output, press `Ctrl` + `c` (or `Cmd` + `c` on macOS). Optionally (and by default), this clears queued messages too.