-
Notifications
You must be signed in to change notification settings - Fork 2
Development
To start hacking on ReadToMyShoe, you must first run the installation steps in Getting Started. After that, there's a few extra steps:
If you want to work on this repo in an IDE, it will be easiest if you put the following lines in your ~/.cargo/config file. This is necessary because web_sys gates unstable features via cfg. I know, this is very weird.
[build]
rustflags = ["--cfg=web_sys_unstable_apis"]
rustdocflags = ["--cfg=web_sys_unstable_apis"]
If you already have rustflags and rustdocflags set, just add the --cfg flags to the end of the list.
To run in dev mode, you must install cargo-watch. This is a filesystem watcher that tells the server to autoreload whenever a file is changed:
cargo install cargo-watch
Running scripts/dev.sh will run the server in "development mode". The server will restart every time you make a change to the source code. When you run the script, it will start a server on localhost:9382.
NOTE 1: Currently, running in dev mode will cause most of the assets to fail to load. This means images will be broken, as well as PWA manifests, and service worker scripts. This is an open issue.
NOTE 2: If you run ReadToMyShoe on your local network or generally without HTTPS, most web browsers will NOT cache anything. This is because Service Workers are only allowed in "secure contexts" (meaning via HTTPS or on localhost).
trafilatura is a fantastic article extraction utility. To play around with it, go to the python_deps/ folder and run
PYTHONPATH=. ./bin/trafilatura
In order to do dev work on RTMS, you have to pay attention to web accessibility. This can be difficult to get started with, and I'm no expert myself. A brief list of tips to get started:
- Read the WCAG intro to web accessibility and click around. There's lots of good resources.
- Learn how to use your computer's screen reader and start using it when testing RTMS.
- On macOS and iOS you'd use Voiceover with Safari. macOS has a great tutorial that will automatically initiate when you turn on Voiceover for the first time
- On Windows you'd use JAWS or NVDA screen readers. I don't have experience with these myself.
- On Android, you'd use TalkBalk. I also have no experience with this myself.
- Use the Lighthouse tab in Chrome dev tools, or click around the Accessibility Inspector in Firefox dev tools.
I don't have a huge amount of documentation on how RTMS works right now. But there's an attempt at a high level overview. See the diagram below.
In words, whenever a client wants to add an article, it gives the URL (or the article text) to the server. The server then fetches the article from the given URL, and runs trafilatura to extract the text content. It then passes the text content to Google Cloud for text-to-speech conversion. Finally, it receives the MP3 file(s) from Google Cloud and saves them in the audio_blobs/ folder.
When a client clicks "Add to Queue" (i.e., the + button next to a library item), it asks for the corresponding MP3 file from the server, and saves it in the IndexedDB local storage.
sequenceDiagram
Note right of Client: Client wants to add article:
Client->>RTMS: http://blog.com/article
RTMS->>Blog: GET
Blog->>RTMS: article HTML
RTMS-->>RTMS: extract text
RTMS->>Google Cloud: article text
Google Cloud->>RTMS: MP3 text-to-speech
RTMS->>Client: OK
Note right of Client: Later: wants to listen to article
Client->>RTMS: Get Article
RTMS->>Client: MP3 text-to-speech
Client-->>Client: save to local storage