3. Architecture - Automattic/stories-android GitHub Wiki

Flows

Typically, a user would engage in the following basic operations in a cyclic way:

  1. Adding a slide
  2. Editing
  3. Saving
  4. Error Handling

The first step is always to add one or more slides to the Story. They'd then do some editing (including adding views, zooming in and out, etc.) and finally save. From the Saving operation the user can transition to 2 other activities: error handling or editing a previously saved Story. Note the library does not offer persistence for the Story elements (only the produced output is saved to disk), so it'd be up to the developer using the library to actually persist the information arriving to them via StorySaveResult events.

Here's a fancy user flow diagram made with the Stories library itself:

In order to implement these flows, the following components work together.

Components

  1. Abstract Activity (ComposeLoopFrameActivity)
  2. Background Surface Manager
  3. Mp4composer
  4. PhotoEditor
  5. CameraX
  6. FrameSaveService / FrameSaveManager
  7. StoryRepository / VM
  8. TextStyleGroupManager

ComposeLoopFrameActivity

This abstract class is an Activity that will let you use the library right away. It provides the essential UI and enables interaction between the user and the library.

BackgroundSurfaceManager

If the ComposeLoopFrameActivity is central to using the library within an Android application, I'd argue the BackgroundSurfaceManager is the brain of it all. It provides a way in which the background surface can be reused for both Live preview, camera recording and Video playback, and allows for quick switching between static image background slides and video background slides.

mp4Composer and PhotoEditor

Based on external libraries, we've decided to make our own forks and incorporate them within the Stories library, adapting them to our needs. The mp4composer library is used to compose videos, allowing us to print our AddedViews on top of each video frame. The PhotoEditor library is in the heart of the creation process and allows adding views on top of a background image. We extended it to support background videos and quick switching through the BackgroundSurfaceManager, usage of different fonts and so on.

CameraX

Google's CameraX library is the recommended approach for camera apps to deal with camera hardware. We use it for live preview / capture mode. Important note on this: as of the time of writing (May 2021) we're stuck with version alpha-06 of the library, given the VideoCapture use case is still in development and alpha06 was the version that offered best results for us. See this open draft PR for more information on the state of things with regards to CameraX upgrades.

FrameSaveService / FrameSaveManager

The process of saving all the frames in a Story is encapsulated in the FrameSaveManager, which is run within the context of an Android foreground Service called FrameSaveService.

StoryRepository / VM

In our MVVM we currently have a simple in-memory singleton that acts as StoryRepository. Given Stories only make sense as long as they're being created or edited, this repository doesn't have persistence or networking capabilities. It is up to the application developer to persist a Story's data, which is accessible through the StoryRepository class.

TextStyleGroupManager

This component is in charge of handling everything related to Text Style. The fonts are preloaded and requested up front upon application startup, so these are available by the time the user needs them.

Next: FAQ