# Poodll MiniLesson for Moodle

**A self-guided, auto-graded language practice activity for Moodle.**

A MiniLesson is a short lesson built from a sequence of *items* — each item is one screen that
presents content or sets the student a task. Students work through the items on their own, and
speaking, listening, reading, writing and vocabulary tasks are graded automatically, either deterministically or using speech recognition and AI. Teachers get the score in the Moodle gradebook, plus per-item reports and recordings/transcripts for review.

There are 27 item types (multiple choice, dictation, gap fills, read aloud, listen and repeat,
free speaking/writing with AI feedback, AI audio chat, vocabulary games, interactive fiction …),
and lessons can be created by hand, imported from CSV/JSON, generated by AI from a topic or a
YouTube video, or copied out of the Lesson Bank.

- **Plugin:** `mod_minilesson` (activity module)
- **Maintainer:** Justin Hunt — poodllsupport@gmail.com
- **Documentation:** https://support.poodll.com
- **License:** GNU GPL v3 or later

---

## Contents

- [Requirements](#requirements)
- [Installation](#installation)
- [Site configuration](#site-configuration)
- [Building a lesson](#building-a-lesson)
- [Item types](#item-types)
- [AI lesson generation](#ai-lesson-generation)
- [Grading, reports and completion](#grading-reports-and-completion)
- [Mobile, LTI and web services](#mobile-lti-and-web-services)
- [Privacy](#privacy)
- [For developers](#for-developers)
- [Support](#support)

---

## Requirements

| | |
|---|---|
| Moodle | 4.3 or later (`$plugin->requires = 2023100900`) |
| PHP | 8.1+ |
| Database | MySQL / MariaDB / PostgreSQL |
| Cloud Poodll account | **Required.** An API user and secret from https://poodll.com |

MiniLesson relies on the Cloud Poodll service for audio recording, text to speech, speech
recognition and AI grading/generation. Without API credentials the activity will not function.
See the [Cloud Poodll API secret](https://support.poodll.com/support/solutions/articles/19000083076-cloud-poodll-api-secret)
article for how to obtain them.

## Installation

1. Copy the plugin folder to `mod/minilesson` in your Moodle code root (on Moodle 5.0+ this is
   `public/mod/minilesson`).
2. Visit **Site administration → Notifications** and complete the upgrade.
3. Enter your Cloud Poodll API user and secret at
   **Site administration → Plugins → Activity modules → Poodll MiniLesson**.

## Site configuration

Settings live under **Site administration → Plugins → Activity modules → Poodll MiniLesson**:

- **API user / API secret** — your Cloud Poodll credentials. The account dashboard page shows
  your subscription and usage.
- **AI Manager** — choose which AI provider handles each AI task (grading speech, grading text,
  grammar correction, CEFR prediction, topic relevance, semantic similarity, content and image
  generation …). Tasks can run through Cloud Poodll or through your own provider keys.
- **Other API keys** — optional OpenAI / Azure / Gemini keys if you want AI tasks to use your
  own accounts rather than Cloud Poodll.
- **Manage items** — enable or disable individual item types site-wide, so authors only see the
  ones you want them to use.
- **Default TTS language and voice**, default item layout, items per page, finish screen
  behaviour, continue-attempt behaviour.
- **Optional features** — Lesson Bank, Push tab, Community page (students hear high-scoring
  submissions that other students consented to share), student-selectable native language for
  AI feedback.

Over 60 speech recognition / TTS locales are supported, including multiple variants of English,
Spanish, French, German, Portuguese, Chinese, Japanese, Korean, Arabic, Hindi and many more.

## Building a lesson

Add a **Poodll MiniLesson** activity to a course. Inside the activity, teacher tabs are:

| Tab | What it does |
|---|---|
| **View** | Preview the lesson exactly as a student sees it. |
| **Items** | Add, edit, reorder, duplicate and delete the lesson items. |
| **AI Generate** | Build a whole lesson from a topic, a passage, a file or a YouTube video using one of ~75 lesson templates. |
| **Import** | Import items from CSV or JSON, and export the current items to JSON. |
| **Lesson Bank** | Pull a ready-made lesson from a shared bank of lessons into this activity. |
| **Grades** | Review attempts, listen to recordings, read transcripts and adjust grades. |
| **Reports** | Per-item and per-user results, attempt details, course-wide attempt reports. |
| **Push** | (Optional, managers only) Push settings from this activity out to other MiniLessons on the site. |

Each item is authored on its own form: a name, instructions, optional media prompt (image, audio,
video, TTS), a layout, and then the settings specific to that item type. Text prompts can be voiced
automatically with text to speech, so no audio recording is required to build a listening task.

## Item types

Grouped by the skills they target. All types are graded automatically unless noted.

### Speaking and pronunciation

| Item type | Description |
|---|---|
| **Listen and Speak** | Audio prompts the student answers by speaking. Classic listen-and-repeat drills. |
| **Speech Cards** | A series of cards with a phrase on each; the student reads each one aloud. |
| **Passage Reading** | The student reads a passage aloud while recording; the reading is scored word by word. |
| **Fluency** | Sentences to say aloud, with each part of the spoken sentence marked good / ok / not good. |
| **Video Shadowing** | Plays a YouTube clip line by line; the student shadows each subtitle line as the words highlight. |
| **Short Answer** | A single question answered by speaking. The author sets the acceptable answers. |
| **MC Audio** | A multiple choice question answered by speaking the chosen answer aloud. |
| **Speaking GapFill** | Sentences with words missing; the student says the completed sentence aloud. |
| **Free Speaking** | An open speaking task, graded by AI with written feedback. Optional community page. |
| **Audio Chat** | A live spoken conversation with an AI partner about a topic or a picture; prompts are editable. |

### Listening and writing

| Item type | Description |
|---|---|
| **Dictation** | Audio player + text field pairs: listen and type what you hear. |
| **Dictation Chat** | Audio prompts presented chat-style, each answered by typing. |
| **Listening GapFill** | Sentences with gaps; listen and type the missing words. |
| **Passage GapFill** | A passage with many words removed; listen to the audio and fill the gaps. |
| **Typing GapFill** | Sentences with gaps to complete by typing. Good for grammar practice. |
| **Free Writing** | An open writing task, graded by AI with written feedback. Optional community page. |

### Reading, grammar and comprehension

| Item type | Description |
|---|---|
| **Multi Choice** | Up to 4 options, one correct. Options can be text, audio or images. |
| **Multichoice Quiz** | Several multiple choice questions about one resource (e.g. a reading passage), asked one at a time while the resource stays on screen. |
| **Word Shuffle** | Sentences with their words scrambled; the student puts them back in order. |
| **Fiction** | A branching, playable story authored in [Yarn](https://docs.yarnspinner.dev/beginners-guide) format. Advanced users. |

### Vocabulary

| Item type | Description |
|---|---|
| **WordCards** | Vocabulary practice: choose or type the correct word from a set of new words. |
| **Scatter** | A grid of cards built from word pairs; clear the grid by matching each pair. |
| **Space Game** | An arcade-style game made from word pairs — "shoot" as many correct words as you can. |
| **Cards** | A series of cards with text, pictures and audio, for introducing new phrases or vocabulary. |

### Content and embedding (not graded)

| Item type | Description |
|---|---|
| **Content Page** | The simplest item: show text or media, then a Next button. Use it to set up later items. |
| **Slides** | A presentation authored in Markdown. Advanced users. |
| **H5P** | Embed an existing H5P activity from the content bank inside the lesson. |

Three further types (**Comprehension Quiz**, **Conversation**, **SmartFrame**) exist as
placeholders and are disabled by default.

## AI lesson generation

The **AI Generate** tab creates complete lessons from a short brief. Roughly 75 lesson templates
ship with the plugin (dialogues, vocabulary sets, reading comprehension, CEFR-levelled lessons,
YouTube-based lessons, audio stories, dictation sets, audio chats and more), each defining which
item types to build and how to prompt the AI. Generated items — including the audio, images and
text — are written straight into the lesson, where you can edit them like any hand-made item.

Lessons can also be created programmatically. `openapi.php` publishes an OpenAPI spec for the
generation web services, and `mcp.php` exposes them over MCP, so an AI agent or a custom GPT can
list templates and item types, create a lesson, and add items to it. See
[Using AI agents to generate MiniLessons](https://support.poodll.com/en/support/solutions/articles/19000175579-using-ai-agents-to-generate-minilessons).

For bulk authoring without AI, the **Import** tab accepts CSV and JSON (`example.csv` and
`example.json` in this folder are working samples), and exports the current lesson to JSON.

## Grading, reports and completion

- Each item reports a grade as the student finishes it; the activity grade is the aggregate,
  pushed to the Moodle gradebook.
- Grading method per activity: highest, lowest, latest, average, or no grade.
- Speaking items are scored from the speech recognition transcript; open speaking and writing
  items are graded by AI against the author's prompt, and return feedback to the student.
- The **Grades** tab lets a teacher play back recordings, read transcripts alongside the target
  text, and override AI grades.
- Reports cover attempts, attempt detail, per-user grading, course-wide attempts and incomplete
  attempts, and can be downloaded.
- Activity completion supports "student must finish the lesson" and a minimum-grade condition.

## Mobile, LTI and web services

- **Moodle app** — supported via `db/mobile.php`; lessons run inside the Moodle mobile app.
- **LTI** — MiniLessons can be launched as an LTI tool from an external platform
  (`lticreate.php`, `ltistart.php`).
- **Web services** — the plugin defines its own service (`db/services.php`) covering grading
  callbacks, item management, and the full AI generation API.

## Privacy

MiniLesson stores personal data: attempts, scores, session data, recordings and transcripts.
Recordings are stored in AWS S3 buckets via cloud.poodll.com, and the Moodle user id appears in
recording and transcript URLs. The plugin implements the Moodle Privacy API for export and
deletion.

## For developers

Item types are subplugins of type `minilessonitem` (declared in `db/subplugins.json`), each living
in `item/<name>/` with the frankenstyle name `minilessonitem_<name>`. A subplugin contains:

| Path | Purpose |
|---|---|
| `classes/itemtype.php` | Extends `\mod_minilesson\local\itemtype\item`. Renders the item and grades it. |
| `classes/itemform.php` | Extends `\mod_minilesson\local\itemform\baseform`. The authoring form. |
| `amd/src/itemtype.js` | In-lesson behaviour. Loaded per item by `amd/src/quizhelper.js`. |
| `templates/<name>.mustache` | The item's template — the filename must match the item name. |
| `lang/`, `pix/`, `version.php` | Strings, picker icon and intro video, plugin version. |

Item settings are stored in generic columns on `minilesson_rsquestions` (`customint1–N`,
`customtext1–N`, …), which each item type maps to meaningful names via class constants — so a new
item setting usually needs no database change.

To add a new item type, copy the closest existing subplugin (`page` is the simplest, `shortanswer`
the simplest graded one) and rename it throughout — namespace, `$plugin->component`, lang file and
strings, template filename, and `pix/` assets. No edit to the parent plugin is needed: item types
are discovered from `item/`, they are enabled unless explicitly disabled on the "Manage item types"
admin page, and each one supplies its own display name through its `pluginname` string. Where the
parent needs behaviour to vary per item type it asks the item type rather than checking its name,
so a new type opts in by overriding a method on `\mod_minilesson\local\itemtype\item` — for
example `uses_boxed_layout()` for the centred-card splash screen, `page_requirements()` to add its
own CSS or JS to the lesson page, or `render_preview()` for a preview button on its authoring form.

Build commands, run from the Moodle code root (the directory holding `Gruntfile.js`):

```bash
grunt amd --root=public/mod/minilesson                 # parent plugin JS
grunt amd --root=public/mod/minilesson/item/<name>     # item subplugin JS — does not recurse!
npm run scss                                           # styles.css is generated — never edit it
```

On Moodle 4.x, drop the `public/` prefix from those paths. Note that building the parent plugin
does *not* rebuild the item subplugins; each one needs its own pass.

## Support

- Documentation and how-tos: https://support.poodll.com
- Account and subscriptions: https://poodll.com/member
- Contact: poodllsupport@gmail.com

## License

Copyright Justin Hunt / Poodll. Licensed under the
[GNU GPL v3 or later](http://www.gnu.org/copyleft/gpl.html).
