view demo/README.md @ 13:16066f0a7127 tip

fixed the problem with brat

# How to Use

The project is divided in two parts **Semantic Analysis** and **Radioplay Rendering** split into three files:

1. `semantic_analysis.sh` - does the semantic analysis part. First it prompts for a story to be input using the system's default text editor. Then it runs the `brat` annotation software to fix mistakes in annotation. After this is done it constructs a radio-play script at `story_processed_script.txt` to be rendered using:
2. `radioplay_render.sh` - Uses `story_processed_script.txt` (fix it first if something is wrong) together with `transcript.xls` and `sfx.xls` to create a rendered radioplay at `output.wav`.


Below we will see the usage for each:

## Preparing

Before running `semantic_analysis.sh` the following steps must be taken:

1. Install `sox` and `festival` (tested with version 2.5) for your operating system, together with the extra voices from `http://festvox.org/packed/festival/2.5/voices/`. If festival 2.5 is not available for your system, I have a bash script `build_festival.sh` which downloads and builds festival and the necessary voices locally.
2. Install `google-chrome`. Only versions < 64 are supported.
3. Create a virtualenv and activate it. Make sure it has python 3: `virtualenv -p python3 your_venv_directory`
4. Run `build_requirements.sh`
5. When prompted for a brat username and password, use username: `au1`/password: `au1`. You can leave the e-mail prompt empty (just press enter). It may ask you to enter your system password: you can just skip this part.

## Running semantic analysis

You are now ready to run semantic analysis. First switch to the directory `semantic_analysis.sh` resides (probably `demo/workspace`) and run `bash semantic_analysis.sh` (careful to use `bash`, simple `sh` won't do). Then:

1. You will be greeted with the system's default editor. Edit your story (but make sure to not change the filename it gets saved as). When finished return to the console and press Enter.
2. If you have a default web browser and `brat` is set up correctly then you will be greeted with the annotated story. If not, run `brat` manually and go to `http://0.0.0.0:8001/index.xhtml#/workspace/story_processed`. You will be greeted with something like:

![brat screensot 1](img1.png)

**First make sure to login using your username and password you defined above**. This is done by hovering on the top right window and clicking on **login**. The annotations there need minor corrections. We see that the system detected two characters (`The Bull` and `The Lion`), a Place (`a meadow`), positioned the Bull to the meadow correctly, as well as a character line (`<cline1>`) and a word that triggers a dialogue (`said`). However, it has not connected the last `The Lion` with the character_line `<cline1>`. In order to fix this, click and hold a line from the annotated `said` to the character `The Lion` and select `WHO` at the popup window. Do the same between `said` and `<cline1>` (by selecting `WHAT`). If everything went well you should have something like below:

![brat screensot 2](img2.png)

Now you can return to the console window and press enter. After a while it will generate a file `story_processed_script.txt` with the radioplay script.

## Rendering the radioplay

After you have generated `story_processed_script.txt` you can render it by running `radioplay_render.sh`.  This script
requires an excel file editor (e.g. LibreOffice calc) available and does two things:

1. Opens two files: `transcript.xls` has the character and narrator lines and the .wav files they are read from. You can 
introduce your own recordings as one of the .wav files. If you don't do that, the character lines are going to be
automatically generated. `sfx.xls` lists the environments detected in the story and assigns a URL to them. The URL must be
an FXive preset. After you have edited saved both those files you can return to the console window and press enter.
2. Renders the file as ../renders/story_processed_script.wav. You can open this with a media player file.