Story Producer (SP app)

Purpose: to enable end users to orally translate still-picture audio-narrated stories with community help, then dramatize, publish and digitally share new local language videos.

End users and target audience: speakers of (minority) languages, some of whom are bilingual in a major language.

End recipients of videos produced: members of local language communities

Developers:

• Original vision and design by Robin Rempel, while with SIL
• Original logo by Jordan Skomer and Mackenzie Sanders
• Software engineers for Prototype app: LeTourneau University students (Jordan Skomer, Hannah Brown, Caleb Phillips)
• Software engineers for v1.2: Cedarville University students (Noah Bragg, Grant Dennison, Robert Jacubec, Andrew Lockridge, Michael Baxter and Abigail Riffle guided by Dr. Seth Hamman)
• Software engineers for Remote Oral Consultant Checker website and app v1.4 and v2.0: Cedarville University students (Blake Lasky, Daniel Weaver, Ann Costantino and Brendon Burns guided by Dr. Seth Hamman)
• Software engineer for app v2.3(MVP)-2.5: John Lambert
• Software engineers for app v2.3 and testing frameworks and Remote Oral Consultant Checker website: Cedarville Univesity students (Aaron Cannon, Justin Stallard, Jonny Taylor, Ben Ratkey, Lindsey Carroll, Nathan Herr)
• Software engineers for Film Producer: Cedarville Univesity students (Donald Shade,...)
• Software engineer for v3.0.2: Chad Dalton
• Software engineers for filtered story list, Film Producer, extensive refactoring based on v3.02: Cedarville Univesity students (Jake Allinson, Nathan ONeel, Clare)
• Software engineer for v3.0.4 - 3.0.6 Dale Hensley
• Software engineer for v3.1 Bryan Wussow
• Software engineer for v3.2 - 3.4 Peter Cheeseman
• Software engineer for v4.0 - current Peter Cheeseman

Translate and produce stories (starting with templates in a major language made up of images, audio and text) by working through these phases:

• [REGISTER project and team information (one time)]
• LEARN or internalize the story
• TRANSLATE+REVISE an audio translation
• COMMUNITY CHECK the draft for naturalness and clarity
• ACCURACY CHECK for Biblical accuracy and approval
• VOICE STUDIO to dramatize the final audio
• FINALIZE create new videos
• SHARE the videos

Creating a signed APK

To install onto a device, an APK needs to be signed. When uploading to Google Play, it has to be signed by the same keystore that was used on the initial upload. For testing on a device using side loading, it can be signed with any keystore. We do not want to check in a keystore to the repo, so developers can either download a pre-made set of files or create their own.

To download pre-made set of files:

• run these commands in the root directory
  • curl "https://sil-storyproducer-resources.s3.amazonaws.com/dev/dev-keystore.jks" -o "dev-keystore.jks"
  • curl "https://sil-storyproducer-resources.s3.amazonaws.com/dev/keystore.properties" -o "keystore.properties"

To create the set of files:

• create a keystore (a .jks file) and save in the root directory.
• create keystore.properties with the values:
  • storeFile=.jks
  • storePassword=
  • keyAlias=
  • keyPassword=
• run gradle clean assembleRelease

Installing the application

• Minimum Requirements:
  • Android 5.x.x
  • 2+GB RAM is needed to create the longer/larger videos
  • an average of 500 MB storage must be available per story template one wishes to create; it is suggested to put templates on an SD card
  • an (Android) file manager
• Typical Install:
  • Install Story Producer app from Google Play Store
  • In the app, tap the Unlocked Demo story to begin a test drive of Story Producer.
  • Use "Download Bible Story Templates" (on the app menu) to install Bible story templates (corrected and vetted by SIL).
  • Please send your User Registration (also on the app menu).
    
    
• Manual or offline install:
  • If you uninstall a version of the app that is v3.3 or later, deleting the app may delete all the template folders and any work you did on the translations. However, when you manually 'Select SP Templates Folder' (recommended), the data is stored in a "user-owned" location and nothing is lost when you unistall the app.
  • Enable a manual install of apk file:
    • Settings(gear icon) -> Security -> (scroll down) Enable "Unknown sources"; disable "Verify apps"
  • Insert SD card if desired
    • You will need approximately 500 MB of storage for each story you wish to produce.
  • Connect to your device via USB (it will show as a drive on your computer)
    • If it does not show up as a drive, swipe down from the top. You should see a notification: USB for charging. Touch it. Select USB for file transfer.
  • Download StoryProducer_v[most recent version].apk and copy the file onto your phone or tablet. Use your file manager on your Android device to open the apk and install it onto your device.
  • Download .bloom template files from Story Producer Resources (these templates are corrected and vetted by SIL) to your computer.
  • Copy the the .bloom files to your SD card. The standard folder there is [SDCARD]/SP Templates
  • Open Story Producer and select the folder "SP Templates" which is the folder that all the templates are in.
  • Continue with User Registration and test drive.

Unit Tests

Organization

• All unit tests are located in the app\src\test\java\org\sil\storyproducer\test directory.
• Test files are named for the class that they test, plus the word "Test" prepended.

  • Example: TestRegistrationActivity contains tests for the RegistrationActivity class.

• Folders in the unit test directory correspond to folders in the source directory.

  • Example: org.sil.storyproducer.test/controller/ contains tests for code that lives in org.sil.storyproducer/controller/

• Individual tests are named according to the following format: FunctionName_When_[Condition]_Should_[DoExpectedBehavior]

  • Example: OnCreate_When_WorkspaceDirectoryIsAlreadySet_Should_NotStartFileTreeActivity

Running the Unit Tests

From the command line:

1. Navigate to the root directory of the repository.
2. Run ./gradlew test (on Linux) or gradlew.bat test(on Windows). Note: You may need to run the gradle wrapper with sudo or make the gradle wrapper executable with sudo chmod +x ./gradlew

From Android Studio:

1. Open the Story Producer project (StoryProducer.iml) in Android Studio.
2. Set the "Project" tool window to show "Local Unit Tests" (or just navigate a the folder containing unit tests).
3. Right click on one of the files or directories that contains some unit tests (this can be the "app" directory, a specific folder, or a single test file.).
4. Click "Run 'All Tests'" (or a more specific option if you chose a folder or file).
5. The "Run" tool window shows the results of the tests. Note: If no tests appear in the "Run" window, you may need to toggle the visibility of passing tests. Currently, the toggle button looks like green checkmark inside of a circle.

Espresso Tests (UI Tests)

Organization

• All Espresso tests are located in the app\src\androidTest\java\org\sil\storyproducer directory.
• Folders in the Espresso test directory should roughly correspond to the screen and/or features they exercise.

Before You Run the Espresso Tests:

The Espresso tests make a couple of assumptions about the state of the emulator/device that they run on. In order for the tests to pass, you must do the following:

1. Create a directory on the phone to act as the Story Producer workspace. The path needs to match the "pathToWorkspaceDirectory" constant defined in app\src\androidTest\java\org\sil\storyproducer\androidtest\utilities\Constants.kt
2. Create a directory on the phone to store resource files that the Espresso tests use. The path needs to match the "pathToEspressoResourceDirectory" value defined in app\src\androidTest\java\org\sil\storyproducer\androidtest\utilities\Constants.kt
3. Copy the "Lost Coin" story template into the espresso resource directory you created in step #2. The name of the directory needs to match the "nameOfTestStoryDirectory" value defined in app\src\androidTest\java\org\sil\storyproducer\androidtest\utilities\Constants.kt
4. Copy an .mp4 video file (the particular length or content doesn't matter) into the espresso resource directory. The name of the .mp4 file needs to match the "nameOfSampleExportVideo" value defined in app\src\androidTest\java\org\sil\storyproducer\androidtest\utilities\Constants.kt
5. Launch your emulator device (or connect a physical one via adb).
6. Run ./gradlew :app:assembleDebug :app:assembleDebugAndroidTest :app:installDebug :app:installDebugAndroidTest from the root directory of the repository.
7. Run adb shell am instrument -w -e debug false -e package 'org.sil.storyproducer.androidtest.runfirst' org.sil.storyproducer.test/androidx.test.runner.AndroidJUnitRunner from the root directory of the repository. (Note that the folder containing ADB must be in your path for this command to work.)

Why is this necessary? The Espresso tests rely on the presence of the "Lost Coin" template as a sample with which to exercise the features of the app. The Espresso Tests also require the workspace to have been set up, but Espresso is not capable interacting with the operating system's file picker, so the WorkspaceSetter class uses UIAutomator to select the workspace.

Running the Espresso Tests

From the command line:

1. Ensure that you have set up your Android device according to the previous section, "Before You Run the Tests." (The device/emulator should be running.)
2. Navigate to the root directory of the repository.
3. Run adb shell am instrument -w -e debug false org.sil.storyproducer.test/androidx.test.runner.AndroidJUnitRunner.

From Android Studio:

1. Ensure that you have set up your Android device according to the previous section, "Before You Run the Tests."
2. Open the Story Producer project (StoryProducer.iml) in Android Studio.
3. Set the "Project" tool window to show "Android Instrumented Tests" (or just navigate to a directory containing Espresso tests).
4. Right click on one of the directories that contains some Espresso tests (this can be the "app" directory, a specific folder, or a single test file.).
5. Click "Run 'Tests in org.sil.storyproducer...'".
6. The "Run" tool window shows the results of the tests. Note: If no tests appear in the "Run" window, you may need to toggle the visibility of passing tests. Currently, the toggle button looks like green checkmark inside of a circle.

Word Links (WL)

• WLs are imported in the workspace, wordlinks/wordlinks.csv is read from the workspace path