Piru

Consume media in foreign languages by translating only the difficult vocabulary and by learning it.

Project Specification

See SPEC.md for the detailed product and technical specification of the MVP.

Development

Install dependencies:

npm install

Configure the OpenAI API key (used for vocabulary extraction):

cp .env.example .env
# then edit .env and set OPENAI_API_KEY

The .env file is ignored by git so your API key stays private.

Run the test suite:

npm test

Initialize the local SQLite database (creates tables if they don't exist):

npm run init-db

The database file is stored in the project root by default. To keep it in a different location, set the PIRU_DB_DIR environment variable before running any commands.

Vocabulary extraction CLI

Extract difficult vocabulary from a text file or large subtitle. The CLI will split big files into chunks so it can handle full-length movies:

npm run extract-vocab -- test/fixtures/en-fr/sample-1.txt
npm run extract-vocab -- "data/subtitles/en/Harry.Potter.and.the.Philosophers.Stone.2001.720p.HDDVD.DTS.x264-ESiR.ENG.srt"

Staging environment

Run a local staging server with a pre-created test account:

npm run init-db:staging   # optional, creates a separate staging database
npm run start:staging

The staging server listens on port 4000 and exposes the account staging@example.com with password staging123.

Algorithms

The src/sm2.js module implements the SM-2 spaced repetition algorithm used for scheduling flashcard reviews.