Interactive story telling embeddable into any website!
This mono repo, formerly called Web-Component, now called Studio-Web, combines four packages:
Here is the quick recipe to spin up the ReadAlongs Studio Web app locally.
# Clone and install the Studio CLI in a Python environment and make sure it's activated:
git clone https://github.com/ReadAlongs/Studio.git
cd Studio
# First create a python environment with conda or venv, activate it, and then run:
pip install -e .
cd ..
# Clone and install the Studio-Web monorepo:
git clone https://github.com/ReadAlongs/Studio-Web.git
cd Studio-Web
npm install
# Run all the servers
npx nx run-many --targets=serve-test-data,serve-web-api,serve,serve-fr,serve-es --projects=web-component,studio-web --parallel 6
After about a minute -- be patient -- six different servers will have started, and you will be able to access the ReadAlongs Studio Web App at these links:
These additional servers are only for testing or indirect use by the web app, not for interactive use:
For more details, keep reading.
This repo is managed using Nx. The biggest change between using Nx and
using npm is you can no longer run npm install
within packages.
Instead, always run npm install
from the root directory of the
repository. You also should only run commands from the root of the repo. See guides below for specific commands.
Clone the repo:
git clone git@github.com:ReadAlongs/Studio-Web.git
Use npm
to install all dependencies:
cd Studio-Web
npm install
If you are only developing the web-component you can run the following to start serving the test-data:
npx nx serve-test-data web-component
Then, in another terminal, run the following to serve the web-component:
npx nx dev-build web-component
Alternatively run together as:
npx nx dev web-component
To run Studio-Web, you first have to build the web-component:
npx nx build web-component --watch
Then serve Studio-Web by running (on port 4200 by default, use --port=nnnn
to override):
npx nx serve studio-web
Ou en français:
npx nx serve studio-web --configuration=development-fr
There are separate production and development serving configurations
for each interface language defined in packages/studio-web/project.json
, so you may for instance also use
development-en
, production-en
, development-es
, production-es
, production-fr
, etc for
--configuration
above. Note that these configurations are only
for the serve
command. To build for deployment, see
below.
We have also defined targets serve-fr
and serve-es
in project.json
so that you can launch the dev configs for all three supported languages at once with:
npx nx run-many --targets=serve,serve-fr,serve-es --projects=studio-web
Note that you will need to also spin-up the ReadAlong-Studio API in order to have Studio-Web work properly. To do that, first clone the Python Package/API repo:
git clone https://github.com/ReadAlongs/Studio.git
cd Studio
pip install -e .
then run:
DEVELOPMENT=1 uvicorn readalongs.web_api:web_api_app --reload
If your Studio sandbox is in a sibling directory to this sandbox, and you Python environment is active, npx nx serve-web-api studio-web
will run that command for you.
Alternatively run together as:
npx nx run-many --targets=serve-test-data,serve-web-api,serve,serve-fr,serve-es --projects=web-component,studio-web --parallel 6
Studio-Web will automatically deploy to https://readalong-studio.mothertongues.org/ every time there is a push to deploy
.
Each push to main
will deploy a dev preview at https://readalong-studio.mothertongues.org/dev/.
When you run npx nx serve studio-web
, that process is actually serving all the files needed
by the Studio-Web application, and it's able to import web-component
and ngx-web-component
,
providing them to the application as needed.
However, web-component
requires a build in order to have the .js files generated and available
to serve or import. In the instructions above, we actually show two methods you can use:
npx nx build web-component --watch
will only build that component, in production mode, and
rebuild it any time you change that component's source code.
npx nx serve web-component
goes further, serving that component, which also requires building
it. It also watches source code for changes. However, it produces a development build, which
may be different from the production build.
In this case, the web-component is being served on port 3333, but the Studio-Web app
just ignores that and uses the copy provided by npx nx serve studio-web
instead.
In three different terminal windows:
Make sure this command is serving the web-component on port 3333 (if
it launches on a different port, you will have to kill the currently
running process using that port, whose PID you can find with fuser -n tcp 3333
):
npx nx serve web-component
Make sure this command is serving the test data on port 8941:
npx nx serve-test-data web-component
Then run:
npx nx test:once web-component
Alternatively run together as:
npx nx run-many --targets=serve-test-data,serve,test:once --projects=web-component
To run the unit tests for Studio-Web, first build web-component
in one of the ways listed
above (or just npx nx build web-component
) if you have not already done so, and then run:
npx nx test:once studio-web
studio-web
is localized in French and Spanish. When you add new strings that need localizing,
you can extract them with
npx nx build web-component # (if not done before)
npx nx extract-i18n studio-web
This will update packages/studio-web/src/i18n/messages.json
with the English strings.
Add or correct their translations in messages.es.json
and messages.fr.json
.
(See packages/studio-web/extract-i18n-lang.ts
for partial automation of that task.)
Finally, run this check to confirm all the required strings are present in each language:
npx nx check-l10n studio-web
Publication to npmjs is mostly automated via the tag-triggered release.yml
CI workflow, but first you have to update the repo with the new version number in multiple places:
peerDependencies
for @readalongs/web-component
in packages/ngx-web-component/package.json.singleFileBundleVersion
in packages/studio-web/package.json.npm install
to reflect the version changes in package-lock.json
.npx nx bundle web-component
to refresh the bundle for studio-web.git tag -a -m'v1.3.0' v1.3.0
.The publication of the web component and its angular wrapper has been automated in the release.yml
CI workflow. The workflow will be triggered when you push the tag vX.Y.Z tag created above.
WARNING: only use this process if the release workflow is broken.
To publish the web component, first you must belong to the
@readalongs organization on
NPM. Then, apply all the version bump and npm install
steps above,
and build both the web component and angular wrapper:
npx nx build web-component
npx nx build ngx-web-component
Run the bundler for single-file html exports:
npx nx bundle web-component
Alternatively run together as:
npx nx run-many --targets=build,bundle --projects=web-component,ngx-web-component --parallel 1
Then, go to the dist directories and publish (but we mean it, don't do this):
cd dist/packages/web-component && npm publish --access=public
cd dist/packages/ngx-web-component && npm publish --access=public
Then you also have to make sure to tag the repo with the new version and create a matching GitHub release, but expect errors since pushing the tag will trigger the automated workflow to do all this again!
Live deployment of the Studio-Web app to https://readalong-studio.mothertongues.org/ has been automated in the deploy.yml
CI workflow, and is triggered by a push to the deploy
branch.
Process:
main
branch and test it on our dev preview page.main
to deploy
.deploy
branch to point to the same commit as the main
branch when we deploy. If you're not sure how to do this, ask for help.To build the web application in the currently deployed configuration
(English interface in the root and French under /fr
, and Spanish under /es
), run:
npx nx build studio-web --configuration=production
npx nx build studio-web --configuration=production --localize=fr --deleteOutputPath=false
npx nx build studio-web --configuration=production --localize=es --deleteOutputPath=false
To build with each interface language in its own directory, run:
npx nx build studio-web --configuration=production --localize=en --localize=fr --localize=es
This will create a complete website under dist/packages/studio-web/
which you can deploy in whatever fashion you like to your server
(e.g., using rsync, scp, sfpt, WinSCP, etc).
Note that the production build expects to talk to the ReadAlongs API at
https://readalong-studio.herokuapp.com/api/v1,
so if you have deployed the API elsewhere, you must:
ORIGIN
environment variable when deploying
the ReadAlongs API to the base URL of your studio-web
instancepackages/studio-web/src/environments/environment.prod.ts
in
your studio-web
instance to point to the URL where you have
deployed the ReadAlongs API (and rebuild, obviously)window.location.href
and your analytics ID will be set to window.location.host
by default.Please read Contributing.md.
This work would not have been possible without the many collaborators who shared their expertise and recordings, including but not limited to the Yukon Native Language Centre, the Kitigan Zibi Cultural Centre, W̱SÁNEĆ School Board, the Pirurvik Centre, Conseil de la Nation Atikamekw, Onwkawenna Kentyohkwa, Owennatekha Brian Maracle, Timothy Montler, Marie-Odile Junker, Hilaria Cruz, Nathan Thanyehténhas Brinklow, Francis Tyers, Fineen Davis, Eddie Antonio Santos, Mica Arseneau, Vasilisa Andriyanets, Christopher Cox, Bradley Ellert, Robbie Jimmerson, Shankhalika Srikanth, Sabrina Yu, Caroline Running Wolf, Michael Running Wolf, Fangyuan (Toby) Huang, Zachery Hindley, Darrel Schreiner, Luyi Xiao, and the Northeastern University students.
Several groups of students in the Foundations of Software Enginering course at Northeastern University have contributed to this project, first in spring 2022 under Michael Running Wolf and then in fall 2022 under Yvonne Coady. We are very grateful for all groups' hard work and contributions, prototypes and ideas. The students involved were: Siqi Chen, Kwok Keung Chung, Koon Kit Kong, He Yang, Yuzhe Shen, Rui Wang, Zirui Wang, Xuehan Yi, Zhenjie Zhou, Yongxiang Chen, Yun Feng, Xiaotong Guan, Mengdi Wei.
If you use this tool, please cite it:
Aidan Pine, David Huggins-Daines, Eric Joanis, Patrick Littell, Marc Tessier, Delasie Torkornoo, Rebecca Knowles, Roland Kuhn, and Delaney Lothian. 2023. ReadAlong Studio Web Interface for Digital Interactive Storytelling. In Proceedings of the 18th Workshop on Innovative Use of NLP for Building Educational Applications (BEA 2023), pages 163–172, Toronto, Canada. Association for Computational Linguistics.
@inproceedings{pine-etal-2023-readalong,
title = "{R}ead{A}long Studio Web Interface for Digital Interactive Storytelling",
author = "Pine, Aidan and Huggins-Daines, David and Joanis, Eric and Littell, Patrick and Tessier, Marc and Torkornoo, Delasie and Knowles, Rebecca and Kuhn, Roland and Lothian, Delaney",
editor = {Kochmar, Ekaterina and Burstein, Jill and Horbach, Andrea and Laarmann-Quante, Ronja and Madnani, Nitin and Tack, Ana{\"\i}s and Yaneva, Victoria and Yuan, Zheng and Zesch, Torsten},
booktitle = "Proceedings of the 18th Workshop on Innovative Use of NLP for Building Educational Applications (BEA 2023)",
month = jul,
year = "2023",
address = "Toronto, Canada",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2023.bea-1.14",
doi = "10.18653/v1/2023.bea-1.14",
pages = "163--172",
abstract = "We develop an interactive web-based user interface for performing textspeech alignment and creating digital interactive read-along audio books that highlight words as they are spoken and allow users to replay individual words when clicked. We build on an existing Python library for zero-shot multilingual textspeech alignment (Littell et al., 2022), extend it by exposing its functionality through a RESTful API, and rewrite the underlying speech recognition engine to run in the browser. The ReadAlong Studio Web App is open-source, user-friendly, prioritizes privacy and data sovereignty, allows for a variety of standard export formats, and is designed to work for the majority of the world{'}s languages.",
}
Littell, P., Joanis, E., Pine, A., Tessier, M., Huggins-Daines, D., & Torkornoo, D. (2022). ReadAlong Studio: Practical Zero-Shot Text-Speech Alignment for Indigenous Language Audiobooks. Proceedings of SIGUL2022 @LREC2022, 23–32.
@inproceedings{Littell_ReadAlong_Studio_Practical_2022,
author = {Littell, Patrick and Joanis, Eric and Pine, Aidan and Tessier, Marc and Huggins-Daines, David and Torkornoo, Delasie},
booktitle = {Proceedings of SIGUL2022 @LREC2022},
title = {{ReadAlong Studio: Practical Zero-Shot Text-Speech Alignment for Indigenous Language Audiobooks}},
year = {2022},
month = {6},
pages = {23--32},
publisher = {European Language Resources Assiciation (ELRA)},
url = {https://aclanthology.org/2022.sigul-1.4}
}
MIT Licensed. See LICENSE for details.