# OpenRoom user manual

## Start your first session

Source: https://openroom.app/docs/start/

Create a deck, present it, collect answers, and finish with Notes.

### Sign in and choose a space

Open [the workspace](https://openroom.app/host/) and sign in with Google. Use the same account on another computer to reach your saved decks and shared spaces. A local development installation can instead provide **Username** and **Password** fields; use the credentials supplied for that installation.

Choose a space in the space switcher. To create one, select **New space**, enter its name, choose **Tutoring**, **Classroom**, or **Training**, and create the space.

| Experience | Navigation and starting material |
| --- | --- |
| Tutoring | Students and groups, their decks, learner access links, and sample language lessons. |
| Classroom | Classes and classroom material, alongside the Library. |
| Training | Shared decks and workshop material in the Library. |

All three experiences use the same deck editor and presentation tools. Choose **Space settings** to change a space's experience later.

### Create a deck

1. Open the space and folder where you want to save the deck.
2. Select **New deck**. A blank deck opens in the editor.
3. Select **Untitled** in the title bar and enter a name. Press **Enter** or select elsewhere to finish.
4. Select **New slide** and choose a template. Replace its example content with your own.
5. Select **Ask** to add a question. For multiple choice, enter a prompt and at least two answers. Mark the correct answer if the question has one.
6. Wait for **Saved** before closing the editor.

To start from a complete language lesson, open a student's or class's Library, select **Sample lessons**, choose a language and level, and open a lesson. Review its questions and homework before teaching.

### Present and invite participation

Select **Present** to open the presenter. Use the slide rail or the forward and back controls to navigate. A slide with a reveal sequence advances one part at a time.

Select **Start session** when you want participants to join. You can start directly from the editor or enable participation while presenting. Starting from an open presenter keeps the current slide and reveal position. The session captures the current saved deck content.

Open **Session menu → Join page** to obtain the participant address. Share the join link, show the QR code, or give participants the eight-character code. Open the audience display on your projector or shared screen; keep the presenter controls on your own screen.

Participants joining with a code use their phones or computers. A session configured for named learner access requires the learner's access link; a roster session requires its individual roster invitation. See [joining instructions](https://openroom.app/docs/participant/).

### Collect and reveal answers

1. Open a question in the presenter.
2. Watch the joined and answered counts.
3. Allow time for answers. For a timed question, the response window closes when its countdown expires.
4. Select the results/reveal control to share the result and, where configured, the correct answer.
5. Advance to the next slide or question.

Result visibility and the ability to change an answer follow the question's settings. Preview the question before using it with a group.

### Finish

Select **End session** and confirm. Ending closes participation. If the session has a durable record, use **Notes** to record outcomes, private tutor notes, and follow-up work. Save the Notes before leaving the page.

Download results while they remain available. Eligible accounts capture a retained results archive when the session ends. The live response data has a short retention period; see [retention and limits](https://openroom.app/docs/limits/).

Leaving the presenter and ending a live session are separate actions. Use **Live now** in the Library to return to an ongoing session.

---

## Library, folders, and decks

Source: https://openroom.app/docs/library/

Organize files, find material, manage copies, and recover items from Trash.

### Find a deck

Choose a space from the space switcher. Open a folder in the tree to show its immediate contents. The breadcrumb identifies the current location. Browser Back, reload, and a copied Library address preserve the folder and selected item.

Select a deck to show its details in the panel. Select **Open** to edit it, or **Start session** to teach from its saved content. A double-click opens the item. Use **Search decks** to search across folders; results include their locations.

The space root can hold decks directly. To file a deck more specifically, create a folder or move it into an existing folder.

Where **List** and **Tiles** are offered, choose the view that helps you find the file. Select an item in either view to use its details panel.

![Library with Camille's folder, a selected deck, and its Open and Start session actions](https://openroom.app/docs/images/library.png)

*The folder location, selected file, and available file actions remain visible together.*

### Create and rename folders

Use **New folder** in the folder browser, type its name, and confirm. To rename a folder, open its context menu and select **Rename**. Enter the new name and press **Enter** or move focus elsewhere to commit it. **Escape** cancels the edit.

Folder creation takes place in the current location. Use the tree and breadcrumb to check that location first.

The folder context menu also provides **New folder inside** and **Duplicate**. Folder duplication recreates the folder hierarchy. Duplicate the intended decks separately and move those copies into the new hierarchy.

### Create, rename, and move a deck

Select **New deck** in the intended folder. The new file opens immediately in the editor. If you opened the Library through a selected student or class, the new deck inherits that context. Otherwise the deck starts without a learner context.

To rename a deck from the Library:

1. Select the deck.
2. Select its title in the details panel.
3. Enter the new name.
4. Press **Enter** or select elsewhere to save. **Escape** cancels the edit.

To move a deck, drag it onto its destination folder or use **Move** in the details panel. The move picker presents the folder hierarchy; filter it to find a destination. Select the intended location and finish the move.

Right-click a row to open its action menu. Keyboard users can select the row and press **Shift+F10**. The details panel also provides the deck's main actions.

### Duplicate and download

Use **Duplicate** to make an independently editable copy. Open the copy and change its title or contents as needed. Check the copy's folder before moving on.

For a portable file, open the deck editor and select **File → Save a copy** from the file controls. The export saves the current content and packages its referenced resources. Wait for the file to finish downloading; a failed resource download stops the export and displays an error. Retry after restoring access to the resource.

Open the downloaded file in [OpenRoom Desktop](https://openroom.app/docs/desktop/). A downloaded file and a cloud deck may carry a link for later synchronization; changes still require the applicable save or sync action.

The Library details panel also offers **Save a copy on this computer** for the selected deck.

### Return to teaching and Notes

Use **Live now** to rejoin an ongoing session. A deck's details and its person's folder provide links to saved results and Notes where available. Follow the **Write the notes** prompt to complete the session record.

Use the person's **Review learner work** link to read homework submissions and publish feedback.

### Trash and restore

Select **Move to trash** in the deck's details panel and confirm. Folder trash is also available through the folder actions. Read the confirmation to check which item and contents are affected.

Open **Trash**, find the item, and select **Restore**. Notes follow the session they belong to; restoring that session restores access to its Notes. Brand kits have their own Trash under **Space settings → Brand kits**.

For permanent removal, choose the permanent-delete action in Trash. Complete the final confirmation in the signed-in browser before the confirmation link expires. Permanent deletion removes the selected record and its dependent data according to the confirmation shown. An expired confirmation requires a new request.

Editing and trash actions depend on your role in the space. See [sharing and permissions](https://openroom.app/docs/sharing/).

---

## Share a space

Source: https://openroom.app/docs/sharing/

Invite colleagues, set their roles, and manage access to shared decks and live sessions.

### Invite a colleague

**Required:** space owner access and the shared-workspace feature on the owner's subscription.

1. Open the space and select **Share**.
2. Select **Invite**.
3. Enter the colleague's email address and choose **Editor** or **Presenter**.
4. Submit the invitation.

The invitation is associated with that email address. Check **Pending invites** on the sharing page to review invitations awaiting acceptance.

Invited colleagues use the space owner's shared-workspace entitlement. They can reach the space from the space switcher and **Shared**.

### Accept an invitation

Sign in with the email address used for the invitation. Open the Library and find the invitation naming its owner and space. Select **Accept invitation** to join and open that space. It then remains available through the space switcher and Shared navigation.

If acceptance fails, check the signed-in email and ask the owner to confirm the invitation and shared-workspace access. A revoked invitation requires a new invitation from the owner.

### Choose a role

| Role | Main permissions |
| --- | --- |
| Owner | Manage the space, invite and remove members, change member roles, and perform all editor and presenter work. |
| Editor | Create and edit decks and teaching records, organize content, manage learner access links, and start sessions. |
| Presenter | Read shared material and start or facilitate permitted sessions. |

Sharing applies to the space's folder tree. Place material requiring a different group of colleagues in another space.

Permissions and paid-feature availability are separate requirements. A feature can require both an appropriate role and the space owner's current entitlement.

### Change a role or remove access

Open **Share**, find the member using search or **Filter by role**, and open the member's action menu.

- **Edit role:** choose the new role and save it.
- **Remove from space:** confirm removal. The member loses access to that space, including further host requests for its shared sessions.
- **Revoke invite:** cancel an invitation that is still pending.

The owner's row is managed by the space. The member role form offers Editor and Presenter for colleagues.

The audience remains in its session after a colleague's removal. Current membership is checked when a colleague attempts further host operations.

### Share live facilitation

Open the ongoing session from the shared space. Use the facilitation controls to join the host team, moderate questions, and hand over presentation. One facilitator holds presenter control at a time; the other facilitators can use the supported moderation controls.

An already-created collaborative session keeps its collaboration setting if the owner's subscription changes. Each colleague still needs current space membership and a valid connection.

### Give learners access

Use a [learner access link](https://openroom.app/docs/learner-links/) for a student or family who needs their Notes, homework, and feedback. Use a [roster invitation](https://openroom.app/docs/participant/#join-with-a-roster-invitation) to give someone a named seat in one live session.

These links have different scopes from a colleague's space invitation. Send the link appropriate to the work the recipient needs to do.

---

## Edit and save a deck

Source: https://openroom.app/docs/deck-editor/

Use the editor, manage draft changes and history, and resolve conflicting saves.

### Open the editor

Select a deck in the Library and choose **Open**. The editor contains a slide rail, the slide canvas, and a task pane. The ribbon contains commands for the selected slide or object. The title bar provides **Present** and **Start session**.

Select a thumbnail to edit that slide. Select text, a picture, or another slide part to show its applicable controls. Choose an empty part of the slide to return to slide-level controls.

![Deck editor showing the slide rail, reading slide, ribbon, and Design task pane](https://openroom.app/docs/images/deck-editor.png)

*Select the slide in the left rail and edit its content and design on the same screen.*

| Task-pane tab | Use |
| --- | --- |
| Design | Content, arrangement, timing, media, response mode, and reveal controls for the selection. |
| Theme | Deck colors, fonts, slide size, masters, and slide overrides. |
| Notes | Presenter notes and available learner-work insertion tools. |
| History | Saved versions and restoration. |

### Write and format content

Select the text you want to edit. Replace its wording on the canvas or use the corresponding text field in the task pane. Use the formatting toolbar for the selected text's font, size, emphasis, color, and alignment. Available controls follow the type of selected content.

Text boxes and pictures on a freeform slide can be dragged and resized using their frames. Structured slides arrange their parts through named layouts; select a **Layout** to change the arrangement.

Use the title in the top bar to rename the deck. Press **Enter** or move focus elsewhere to commit the name; **Escape** cancels.

### Add and edit objects

On a slide that supports freeform objects, use **Home → Text box** or **Insert → Text box**. Enter the text on the canvas or in the selected object's **Text box** field. Drag its frame to move it and use its handles to resize it. The task pane reports the box's size and position as percentages of the slide.

Use **Insert** for Picture, HTML, Web page, PDF, and Reading objects. Select an existing object and choose **Change…** for a picture or **Edit…** for document and embedded content. **Remove** deletes that object. The enabled insert controls identify the kinds supported by the current slide.

For structured lists, select a card, step, term, answer, or other part and use its **Add** / **Remove** controls. Select the part's text before applying formatting. Use the deck's heading and body fonts under **Theme** to keep the whole presentation consistent.

### Use the ribbon

| Tab | Main controls |
| --- | --- |
| File | Save a portable copy; Desktop adds local save and synchronization. |
| Home | New slide, duplicate/delete, layouts, timing, simple reveals, objects, questions, and PowerPoint embed code. |
| Slide | Individual slide types and breakout insertion. |
| Insert | Text, pictures, HTML, web pages, PDF, and reading objects. |
| Questions | Question dialog, gaps, matching, and classroom activities. |
| Reveal | Reveal mode, playback, Show all, and Edit order. |
| View | **Start from here** to rehearse the selected slide. |

The **plan.yaml** menu copies the command for reading the current deck through the CLI. Follow [command-line setup](https://openroom.app/docs/cli/) before using it.

### Save changes

Cloud editing saves a rolling draft after a short pause. The status shows **Unsaved changes**, **Saving…**, **Saved**, or a save error. Wait for **Saved** before closing the tab. A failed save retries automatically; if the error remains, keep the editor open, restore the connection, and make a further edit to retry.

Drafts preserve unfinished fields so you can return to them. Starting participation validates the content and saves a version first. Complete any question named in the readiness message before starting the session. A draft can be readable in the editor while its unfinished question still needs an answer or prompt.

The **Save a copy** and **Copy embed code** actions also save the current content before producing their output. A session already in progress uses the content captured when it started; edit the deck for a later session or use the live insertion tools for immediate additions.

### Restore a version

1. Open **History** in the task pane.
2. Find the version you want by its number and saved date.
3. Select **Restore**.
4. Review the restored content in the editor.

Restored content becomes your working draft. Starting or exporting saves it through the normal versioned workflow. Later versions remain available in History.

### Resolve a conflicting draft

If another client saved a newer version, the editor preserves your draft and displays two choices:

- **Keep this draft:** continue with the visible content, based on the latest saved version.
- **Use saved version:** replace the working text with the latest saved content.

Review the difference before choosing. Copy important text elsewhere if you need to combine overlapping changes manually. Starting participation waits until the conflict is resolved.

### Review overflow

When content extends outside its intended area, select **Review overflow**. Choose an affected item to focus its existing editor. Shorten the text, reduce its formatting size, change the layout, enlarge its text box, or split the material across slides.

Long reading and homework documents have their own scrolling areas. Check both the slide preview and the document itself before presenting.

### Open portable and prepared content

Open `.openroom` files in Desktop. For agent-authored YAML or JSON, use the connected agent or [CLI workflow](https://openroom.app/docs/cli/) to validate and save the outline into a deck, then open that deck here to review the result.

---

## Slides, templates, and reveals

Source: https://openroom.app/docs/slides/

Build slide sequences, add detail slides, prepare timers, and control reveal order.

### Add and organize slides

Select **New slide** to open **Choose a slide**. Browse **Essentials**, **Language**, **Questions**, or **Group work**, or search by template name. Select a template to insert it after the current slide. **Blank slide** provides a freeform starting point.

Templates inherit the deck's design. Replace their example text, questions, and private notes before teaching.

| Template group | Typical material |
| --- | --- |
| Essentials | Title, section, objectives, statement, text and image, comparison, process, cards, quotation. |
| Language | Vocabulary, dialogue, grammar, reading, listening, role-play. |
| Questions | Choice, confidence scale, ranking, open response, fill-the-gaps, matching. |
| Group work | Group task, timed discussion, recap and next steps. |

Use the rail's reorder gesture to move a slide. **Duplicate** creates a separate editable copy, including the slide's question where applicable. **Delete** removes the selected slide from the working deck. Use [History](https://openroom.app/docs/deck-editor/#restore-a-version) to recover saved content.

The **Insert** ribbon and slide context menu also offer individual content types: title, statement, cards, steps, term, media, activity, timer, join instructions, debrief, and break. Use the type that matches the content; its available layouts and properties follow that type.

### Insert a workshop sequence

In **Choose a slide**, select **Workshops**. Select a sequence to insert its slides, questions, and facilitator notes together. Review the stated duration and adapt the examples to your group.

For shared answers, select a question and choose **Design → Responses → One per group**. Assign group members and spokespersons after participants join; see [facilitation](https://openroom.app/docs/facilitation/).

### Reveal content progressively

Use **All at once** to present a slide's content together. Use **One at a time** to reveal its parts in sequence. Select **Edit order** or the task pane's **Reveal** controls to arrange the reveal sequence and group parts that should appear together.

Preview with the ribbon's playback controls. During presentation, the next action reveals the next part before advancing to the next slide. Backward navigation reverses the reveal position.

Correct answers follow the question's result controls. Revealing ordinary slide content and revealing a question's answer are distinct actions.

### Add a breakout slide

Select the parent slide part and choose **Add breakout slide**, then select the detail content to add. The detail belongs to that part of the parent slide. Edit it through its entry in the slide rail.

During presentation, open the detail from its parent part and return to the parent when finished. Use this for worked examples, extra explanation, or a supporting exercise. Remove the breakout through its task-pane controls when it is no longer needed.

### Prepare a timer

Insert **Timer** and set its minutes and seconds. Choose a style: **Countdown**, **Count up**, **Bar emptying**, **Bar filling**, **Hourglass**, or **Ring**.

Choose **Whole slide** for a dedicated timing screen or **In the corner** for a smaller clock. **Keep on next slide** retains the clock as you move forward. Timer text tokens insert the current duration into the title; the task pane previews the resulting wording.

The presenter provides start, pause, reset, and one-minute adjustments. A slide timer supports activity timing. A question countdown controls when that question stops accepting answers.

### Prepare learner pages

Use the editor's homework and recap areas for material learners will read after the lesson. These are scrollable documents, so longer instructions can remain readable without squeezing them into the slide dimensions.

Add typed homework tasks alongside prose, check that prompts are self-contained, and include any required source text or exercise. Use the [homework instructions](https://openroom.app/docs/homework/) to choose recipients and publish changes.

---

## Questions and answer settings

Source: https://openroom.app/docs/questions/

Author questions, choose response formats, and control results, correctness, and timing.

### Add a question

Select **Ask** in the deck editor. Choose **Multiple choice**, **Ranking**, **Fill the gaps**, **Match**, or **Open answer**, complete the prompt and answers, and add the question. **New slide → Questions** also provides question templates, including **Confidence** for a scale.

For numeric questions, a dedicated Q&A question, or advanced response policies, prepare the typed outline through a connected agent or the CLI, then open the saved deck to review it. The outline carries all eight interaction types below.

### Choose a response format

| Type | Authoring and participant behavior |
| --- | --- |
| Multiple choice | Supply 2–10 options. Mark correct options when applicable. A single-choice question accepts one option; a multiple-answer question accepts a set of options. |
| Scale | Define the minimum and maximum values and optional endpoint labels. Participants choose a value. The difference between endpoints must be 2–10. |
| Numeric | Ask for a number. Optional lower and upper bounds constrain entries. A tolerance can define acceptable estimates where configured. |
| Open answer / text | Collect a short text response. Set accepted answers for a knowledge check or leave the question open-ended. The default length limit is 200 characters; the maximum configurable limit is 500. |
| Q&A | Collect questions and upvotes. Use session-wide audience Q&A for questions that should stay available alongside the deck. |
| Ranking | Supply 2–6 options. Participants put them in order. A configured correct order supports an ordering exercise; otherwise the result combines audience priorities. |
| Fill the gaps | Write the sentence and define 1–8 gaps, each with accepted wording. Choose typed answers, a word bank, or per-gap choices. |
| Match | Supply paired left- and right-hand items and their correct mapping. Participants connect the items before submitting. |

### Edit options and correctness

Select a question part on the canvas. Edit its text through the selected part's field. Use **Add** and **Remove** to adjust its list. Select a choice option and use **Mark correct** or **✓ Correct** to toggle its correctness.

For a multiple-answer question, configure the multiple-selection policy through the outline so participants can select all intended answers. Merely marking more than one option correct does not itself change the selection policy.

A text question can carry several accepted answers. Matching uses the configured pairs. Ranking requires an explicit correct order for a scored ordering task. Complete these policies before starting; learners receive answer keys through the reveal or practice-check workflow.

### Create fill-the-gaps exercises

1. Enter the complete sentence in **Ask → Fill the gaps**.
2. Select the wording to remove and use the gap action. In the task pane, **Gap selected text** creates a gap from a selected range; **Add a gap** adds another.
3. Select each gap and check its primary answer. Add alternatives under **Also accepted**.
4. Choose **Typed answer**, **Word bank**, or **Choices**.
5. For **Word bank**, add optional **Word bank extras** as distractors. For **Choices**, enter **Wrong options** for each gap.
6. Preview the exercise and check that every gap has a valid answer.

The word bank is optional. A one-gap typed exercise is valid. Removing a gap restores the associated wording to the prompt through the editor's structured controls.

![Selected gap-exercise prompt with text editing, gap creation, and response-style controls in the task pane](https://openroom.app/docs/images/gap-exercise.png)

*Select the prompt to edit its wording and choose typed answers, a word bank, or choices.*

### Set answer and reveal policies

Question-level settings override the deck defaults. Configure advanced policies in the outline using an agent or CLI:

| Policy | Effect |
| --- | --- |
| Result visibility | **Live** exposes aggregates while responses arrive. **Hidden until close** withholds them until the response window closes. |
| Answer changes | Allows a participant to replace an answer while the question accepts responses. |
| Countdown | Sets the response window in seconds; expiry closes the question. |
| Peer instruction | Enables a second choice vote after discussion, preserving the first round for comparison. |
| Individual / One per group | Collects separate participant answers or one shared answer from each assigned group's spokesperson. |

The editor exposes **Individual** and **One per group** under **Design → Responses**. Check the live preview and participant behavior when preparing advanced policies.

### Choose a results display

Result styles depend on the interaction type. Choice supports bars, columns, donut, pie, radial and compact count/card variants; scales support dots, gauge, bars or a scale; numeric questions support histogram or a number; text supports a list, cards or word cloud; ranking supports ordered bars and ordering views. Gap and matching exercises use their exercise-specific displays.

In live controls, open the chart/display menu to choose an applicable style and its available presentation options. Use short option labels and inspect the audience display before revealing a result.

For peer instruction, close the first vote, discuss the question, then start the second vote. Compare the rounds after the second response window closes. **Undo revote** restores the first round and discards the second round's responses.

---

## Themes, masters, and brand kits

Source: https://openroom.app/docs/design/

Set the deck's visual design and reuse shared colors, logos, fonts, and slide masters.

### Set a deck theme

Open **Theme** in the editor's task pane. Choose a theme family, then adjust its colors and heading and body fonts. Use the slide preview to check text and chart contrast.

Set **Slide size** to **16:9**, **16:10**, or **4:3**. That ratio applies throughout the deck. Editor, presenter, audience display, and participant Slide view preserve the same slide composition; unused screen space is letterboxed as necessary.

Changing the ratio changes the available canvas shape. Review every slide for overflow after changing it.

### Create and apply a master

A master supplies recurring decoration, margins, backgrounds, logo, and footer.

1. Under **Slide masters**, select an existing master or choose **New master**.
2. Enter a **Master name**.
3. Set **Content margin**, decoration, footer, and background.
4. Add a logo and a useful **Logo description** if needed.
5. Choose **Use on this slide** for the selected slide or **Set as default** for the deck's default master.

The content margin ranges from 3% to 12%. A deck supports up to 20 masters. **Remove master · use deck default** removes a selected master and returns its uses to the deck default; at least one master remains.

### Configure backgrounds and logos

Choose **Solid** or **Gradient** for a color background. For a gradient, set both colors and the angle. Use **Choose background image** to select a file or **Use an image address** to provide an address. Adjust focal points to keep the important part visible; set the overlay color and opacity to maintain readable text.

Use **Choose logo image** for a logo, then enter its description. **Remove logo** clears it. **Use theme background** restores the master's theme background.

Uploads require an editable space. Desktop can embed chosen image files into a local `.openroom` file. See [media formats and storage](https://openroom.app/docs/media/).

### Override one slide

Under **This slide**, choose **Customize this background** to override the master's background. **Use master background** removes that override. Select **Hide logo, footer and decoration** when a slide needs an uncluttered canvas.

**Reset to deck master** clears the slide's design overrides while retaining its template association. Review the result before continuing.

### Create a shared brand kit

**Required:** editor or owner access for authoring, plus branding availability on the space owner's account.

1. Open **Space settings → Brand kits**.
2. Select **New brand kit**.
3. Enter a **Kit name** and configure its colors, typography, masters, backgrounds, and logo.
4. Review the chart palette preview and any contrast warnings.
5. Select **Save brand kit**.

Open an existing kit and select **Edit brand kit** to revise it. Its detail page provides **Move to trash**; the brand-kit Trash provides **Restore brand kit** according to your management permissions.

### Apply a brand kit

In the deck editor's **Theme** pane, choose a kit under **Brand kit** and select **Apply to all slides**.

Applying copies the kit's colors, fonts, and masters into the deck and resets individual slide backgrounds to the kit. Slide content and layouts remain in place. The copied design belongs to the deck, so a later change to the shared kit requires another explicit application to that deck.

### Change the live interface theme

Live session controls also provide the shared interface themes **Default**, **Chalkboard**, **Paper**, **Projector**, and **Sherbet**, with light/dark presentation where available. These control session interface styling. The deck's saved design remains the source of its slide composition.

---

## Pictures, audio, and embedded material

Source: https://openroom.app/docs/media/

Add media and reading material, prepare listening activities, and make portable copies.

### Insert a picture

Select **Picture** from the editor's insert controls. Choose a source:

| Source | Procedure |
| --- | --- |
| Stock photos | Enter a search term, select a result, and insert it. Stock search requires the service to be configured and reachable. |
| This space | Select an existing uploaded image from the space's media library. |
| Upload | Choose a file to upload to the current space. Requires editor or owner access. |
| From a link | Enter the picture address, load it, and insert it. |
| This computer | In Desktop, choose an image to embed in the local file. |

Select the inserted picture to change or remove it, set its size and placement, adjust the focal point, and edit **Alt text** and **Caption**. Use meaningful alt text for information conveyed by the image.

Supported uploaded images are PNG, JPEG, WebP, GIF, and AVIF. Individual uploaded media files are limited to 20 MiB.

### Prepare listening audio

Insert an **Audio** slide. In **Design → Audio**, select **Choose audio file** or enter an **Audio address**. Supported recordings are MP3, WAV, and M4A. Enter a **Recording label**, optional caption, and transcript.

Choose the listening mode:

- **Room audio:** playback comes from the presenter's device. Connect that device to the room speakers.
- **Individual listening:** participants receive their own playback controls.

Use the preview player to test the file. Transcripts are withheld from learners until **Show transcript** is selected while presenting. During live delivery, use play, pause, seek, transcript, and retry controls as needed. A browser may require a user gesture before it can play audio.

### Insert video

Choose the video/media insertion option and set its address and descriptive text. Preview the result in the presentation view before the session. Linked services can require internet access and allow or deny embedding according to their own policies.

For portable offline material, use resources supported by the `.openroom` package. An external video address remains dependent on its source service and connection.

### Add reading material and Markdown

Use the reading/Markdown insertion controls for passages, lists, and structured explanatory text. Edit the Markdown, preview it, and save it into the selected box or reading area.

Reading content can scroll inside its own area. Give the passage a clear title and check its phone presentation through **Reading** view. For a long passage, use a reading document instead of reducing the entire text to a small slide font.

### Embed a website

Choose **Insert → Web page**. Enter the **Web address** and an **Accessible title**, then insert it. The destination must permit embedding.

If the page refuses to load inside the slide, use the provided open-page action or **Import as reading** where offered. Importing as reading converts available page text into editable reading material. Check the imported wording and formatting before presenting.

### Insert a PDF

Choose **PDF**. For a linked document, select **From a link**, enter its **PDF address**, add an accessible title, and insert it.

In Desktop, select **From this computer → Choose PDF…**. Choose an inclusive page range, give the extracted document an accessible title, and insert it. The source PDF can be up to 100 MiB; the extracted embedded resource must fit the 20 MiB per-resource package limit.

Only the selected pages are copied into the file. Review them in the deck before sharing or starting an online session.

### Add HTML or SVG content

Choose **HTML**, enter markup in **HTML or SVG**, and optional styles in **CSS for this box**. Review the preview and save it. Use this for a self-contained diagram or formatted visual.

Embedded markup is sanitized. Script execution, unsafe links, and disallowed resources are removed or rejected according to the supported content contract. Keep the visual self-contained and test the sanitized preview rather than relying on an external page's scripts.

### Store and share media

Uploaded media is accessible through an unguessable asset address. Anyone who receives that address can retrieve the file. Choose teaching material appropriate for that sharing boundary.

Desktop embeds supported local resources in the `.openroom` file. A package supports up to 100 resources, 20 MiB per resource, and 50 MiB combined. Linked web pages and external services still require connectivity.

When downloading a cloud deck, OpenRoom resolves and packages referenced resources. If a resource cannot be retrieved, correct its address or access and retry the export. Starting an online session from a local file uploads the resources needed by participants before the session starts.

---

## Present, annotate, and explain

Source: https://openroom.app/docs/present/

Navigate slides, use an audience screen, mark passages, and control listening and word lookup.

### Open the presenter

Select **Present** in the deck editor to start from the beginning, or use the ribbon's presentation action for the selected slide. Use **Previous**, **Next**, or the slide rail to move through the deck.

On a slide with progressive reveals, Next reveals the next group before moving on. Previous reverses the reveal sequence. Select **Edit deck** to return to authoring.

Select **Start session** to enable audience participation. The current slide and reveal position carry into the live session.

### Use a projector or second display

During a live session, open **Session menu → Stage**. Move the audience window to the projector or the screen you share, then use that window's fullscreen controls. Keep the host window on your own display.

Desktop provides **Audience screen** and buttons for detected external displays. Choose the intended display to open the separate audience window. Check the image and audio output before beginning.

The audience display follows the host's live navigation and reveal state. It shows audience material and results; private teaching notes stay on host surfaces. For an active question, **Blank** toggles audience result visibility while retaining the received answers.

### Mark text and draw

In the live ribbon, choose the annotation tool and color. Select or drag across words to highlight, underline, or mark the passage with the available text shapes. Word-based marks follow the selected words when the display size changes.

Use the pen for a freehand stroke on the slide. Freehand strokes use slide coordinates; they appear in the participant's **Slide** view. **Reading** view retains text-anchored marks. Switching back to Slide restores the freehand view.

Double-click a phrase mark to remove that mark. Use the clear action to clear annotations. Moving to another slide clears the live ink; hiding and revealing the same content preserves its text marks while you remain on that slide.

### Look up a word

First set the space's **Students’ language** and **Teaching** language in **Space settings**. Choose the students' language first; it determines which teaching-language pairs are available.

Activate **Look up** in the live controls and select the word in the passage. Review its meaning and the available dictionary forms. Choose the form or explanation you want to show. Open and close the meaning view as needed, then return to the passage.

In the deck editor, selecting a word for lookup displays its definition in the task pane. A failed lookup can indicate a missing language pair, an unavailable dictionary service, or a word with no matching entry. Correct the language pair or try the word's base form.

### Play a listening activity

Open the audio slide and use **Listening controls**. Choose **Room audio** to play from the current presenter's device, or **Individual listening** to give each participant their own player. Start playback with the player controls; use pause or seek to revisit a section.

Choose **Show transcript** when the class is ready to read the transcript. Hide it again for another listening pass. Use the retry/replay controls when repeating the activity.

Presenter handoff changes who controls the live listening settings. Room audio belongs to the presenter's device; check that the new presenter's audio output is ready after a handoff.

### Add material during a session

Use the live **Insert** controls to add an explanation, supported media, or a new question at the current point. Complete the insertion form and show the new material. Use the corresponding edit action to revise editable live material.

Live additions belong to that session. To reuse them later, deliberately incorporate the material into the saved deck. The original deck remains the source for future starts.

---

## Run a live session

Source: https://openroom.app/docs/live-session/

Manage participation, question state, results, remote control, and session recovery.

### Choose participant identity

Prepare the deck's identity policy through a connected agent or the typed outline before starting:

| Identity mode | Entry and identity |
| --- | --- |
| Anonymous | Join with the session code; individual names are withheld. |
| Pseudonymous | Join with the code and receive a generated session name, with handle-based recovery. |
| Identified | Use a personal learner credential belonging to the deck's context; joining opens after the teacher starts. |
| Roster | Use a host-issued invitation naming one seat in one session; lobby entry is available. |

An identified deck needs a real student, group, or class context. Named roster sessions require the named-invitation entitlement. See [learner links](https://openroom.app/docs/learner-links/#use-named-live-participation) and [roster administration](https://openroom.app/docs/cli/#issue-named-roster-invitations) to prepare the corresponding entry addresses.

### Start and share entry

Select **Start session** from a deck or its presenter. The current deck content is saved and captured for the session. The host header shows the connection state, joined count, and answered count for the current question.

For code-based participation, select the join code to copy its link, or open **Session menu → Join page**. Share the code or QR code with the audience. A named learner session uses personal [learner access links](https://openroom.app/docs/learner-links/). A roster session uses individual invitations for its named seats.

Select **Stage** in the session menu to open the audience display. If its link has not loaded, select **Stage — retry**.

### Open, close, and reveal a question

Select the question in the rail and open it on the audience display. The selected preview and the active audience question may differ; use the open/show action when you intend to change the audience's current question.

| Action | Result |
| --- | --- |
| Open | Make the question active and accept responses. |
| Close | Stop accepting responses. Aggregates follow the configured visibility policy. |
| Reveal results / Call out the correct answer | Show the result and configured correctness information. |
| Hide results | Hide the revealed result while retaining received responses. |
| Reopen | Accept responses again for that question, retaining its existing answers. |
| Next | Reveal the next content group or continue to the next slide/question. |

A question countdown closes responses automatically when time runs out. Closing a question and ending the session are different operations.

Use the chart menu to change the current result display. Text responses can be hidden individually from the result display and restored through moderation controls. Review what the audience will see before projecting sensitive free-text answers.

![Live presenter with revealed choice results, answer counts, current slide, and question controls](https://openroom.app/docs/images/live-results.png)

*The current question, revealed answers, and presenter controls share one view.*

### Run a second vote

For a choice question prepared with peer instruction:

1. Collect and close the first vote.
2. Let participants discuss their reasoning.
3. Start the second vote using the revote control.
4. Close the second vote and compare the rounds.

The first-round aggregate is retained for comparison. **Undo revote** restores the first round and discards the second round.

### Freeze participation

Select **Freeze** to pause submissions and hide participant text on the audience display. Use **Unfreeze** to resume. This is useful when a response needs moderation or the room needs your attention.

Use the ordinary question-close action when only the current question should stop receiving answers. Use **Blank** to toggle the current question's audience result visibility.

### Control from a phone

Open **Session menu → Copy remote link** and open that link on your own phone. The remote provides the current question's actions, previous/next navigation, applicable clock and listening controls, freeze, and session ending.

The remote link carries host authority. Send participant links to the audience and keep the remote link for the presenter. A colleague with shared-space access can obtain their own authorized session connection.

### Reconnect and recover

| Connection label | Meaning and action |
| --- | --- |
| Connecting | Wait for the session connection to initialize. |
| Live | The session is receiving live updates. |
| Polling | Updates are arriving through periodic requests. Continue, allowing for a short delay. |
| Offline | Restore network access. Check the latest slide and question state after reconnecting before sending another action. |

Use the same browser to retain its session connection. On another device, sign in and use **Live now** in the relevant Library. Shared facilitators should also re-enter through their shared space.

If an operation fails, read the error and wait for reconnection before retrying. Check whether the intended slide or response state has already changed. Starting again deliberately creates another audience session; use recovery to return to the existing one.

### End or leave

To finish participation, select **End session**, then confirm **End this session?** Participants disconnect and results become final. Continue to Notes or export results as needed.

To return to the deck or Library while participation continues, use the corresponding exit action. The session stays reachable under **Live now** until it ends. Idle sessions also expire according to the [retention policy](https://openroom.app/docs/limits/).

---

## Q&A, groups, and co-facilitation

Source: https://openroom.app/docs/facilitation/

Moderate audience questions, collect shared group responses, and pass presenter control.

### Open audience Q&A

Enable audience Q&A in the deck's prepared outline through a connected agent before starting. During the session, participants can submit questions and upvote questions while you continue through the deck.

Open **Session menu → Q&A desk** for the moderation view. Review submitted questions, hide inappropriate or duplicate items, restore hidden items when appropriate, and spotlight a selected question on the stage. Clear or change the spotlight when moving on.

Select **Show Q&A on stage** to project the question list and **Take Q&A off stage** to return to the deck. The presenter's Q&A tab offers the same switch as **Stage Q&A**. Use **Unspotlight** or **Remove from stage** to return a highlighted question to the list.

In the presenter's question cards, **Answered** records that you have dealt with a question and hides it from the stage. That answered marker is kept in the current browser session; the question's hidden state is shared with the live session.

Use **Copy Q&A desk link** when opening your moderation view on another device. Treat that link as a host credential. A shared colleague should use their own authenticated session access when available.

Question-specific Q&A is also available in prepared outlines. Its response collection follows that interaction's active state; session-wide audience Q&A accompanies the whole session.

### Set up shared group answers

Before teaching, select each intended group question in the deck editor and choose **Design → Responses → One per group**. Other questions can remain **Individual**.

During the session:

1. Wait for participants to join.
2. Open the **Groups** panel and select **New group**.
3. Enter a **Group name**.
4. Find and select the participants who belong to it.
5. Select **Make spokesperson** for the member who will send the shared answer.
6. Select **Save group**.

The spokesperson submits on the group's behalf. Other members see the group's answer state. The host's answered count identifies group answers when the active question uses group responses.

### Change groups during teaching

Select **Edit group** to change membership or choose another spokesperson. A participant belongs to one current group; selecting someone from another group moves them when the change is saved.

Earlier answers stay associated with their original group. Changing the spokesperson retains the group's submitted answer. **Dissolve** removes the active group arrangement while retaining its submitted responses. A new group begins with a fresh answer identity.

Use this behavior deliberately when regrouping between activities: review the current question and answer-change policy before a new spokesperson responds.

### Work with another facilitator

**Required:** shared-session collaboration enabled for the session, current membership of its space, and an authorized host connection.

Have each colleague open the ongoing session through the shared Library. When multiple facilitators are connected, the facilitation strip identifies the current presenter.

- The presenter changes slides, controls reveals, freezes participation, and ends the session.
- Other facilitators can moderate responses and manage groups using the controls available to them.

To hand over, select **Pass presentation** and choose the colleague. Confirm that their strip shows **You are presenting** before they take over. The audience remains in the same session with its existing answers.

When recovery is permitted, **Take back presentation** restores presenter control. Use this if a handoff left the active presenter unavailable.

### Prepare a workshop recap

Open **Session menu → Prepare workshop recap**. Select the results and public material to include, preview the recap, and download it. Review selected free-text material before sharing. See [results and recaps](https://openroom.app/docs/results/) for refresh behavior and exports.

---

## Join and participate

Source: https://openroom.app/docs/participant/

Enter a session, answer questions, ask the host, and recover your connection.

### Join with a code or QR code

Open [join.openroom.app](https://join.openroom.app/) on your phone or computer. Enter the host's eight-character code and select **Join**. A QR code or join link fills the code for you.

Codes are case-insensitive. Use the code displayed for the current session. When the host has not opened a question yet, keep the page open and wait for the next activity.

In a session using generated names, note the name shown under **Your session name**. It identifies your participation in that session and can help you rejoin from another browser.

### Join with a personal learner link

Open the personal session-join address your teacher supplied and select **Join**. It combines the current session code with your learner credential. The displayed name comes from the learner identity attached to that credential. Keep the separate lesson-page link for homework and feedback.

Named learner sessions admit participants after the teacher starts. If you arrive early, wait and try again once the lesson is live. Keep using your own link so your work stays associated with the correct person.

### Join with a roster invitation

Open the individual invitation supplied by the host. It identifies your named seat in one session. The name is supplied by the host, so check it before continuing and contact the host if it is wrong.

Roster invitations can admit participants into the lobby before the host starts. They remain specific to their session. For a later session, use its new invitation.

### Answer a question

| Question | How to answer |
| --- | --- |
| Single choice | Select one option. It sends immediately. |
| Multiple choice | Select the options, then select **Send … selected**. |
| Scale | Select the value that matches your answer. |
| Numeric | Enter the estimate using the stated unit, then select **Send answer**. A decimal comma or point is accepted. |
| Text | Type your response and send it. Use the character counter and available accent characters. |
| Ranking | Reorder the items with the move controls, then send the completed order. |
| Fill the gaps | Fill each blank, choose from its options, or use the word bank; then send the answer. |
| Match | Choose the matching right-hand item for each left-hand item and send the completed matches. |

Wait for **Answer received** or the displayed answered state. When **Don't know** is available, use it to submit that response explicitly.

If the host permits answer changes, use the change/edit action while the question remains open. Once the response window closes, wait for the result or the next question. Results and correct answers appear according to the host's reveal settings.

### Answer as a group

For a group question, check your assigned group and spokesperson. Discuss the answer together. The spokesperson sends one response for the group; other members follow the shared answer state.

Ask the host to assign a group or spokesperson if the page is waiting for one. For individual questions, each participant answers separately.

### Read slides and listen

**Slide** preserves the projected slide's layout. Select **Reading** for a reading-oriented view of its content. Text highlights follow the words in both views; freehand pen marks belong to Slide view.

![Phone Reading view with a complete French passage and the Slide and Reading controls](https://openroom.app/docs/images/phone-reading.png)

*Reading view adapts the passage to the phone's width.*

For **Individual listening**, use your own audio player. In a room-audio activity, listen to the host's playback. The transcript appears when the host releases it.

### Ask a question

When audience Q&A is enabled, open its question area, type your question, and send it. Use the upvote control beside a question to support it. The host can moderate and spotlight questions.

### Rejoin

Reloading in the same browser normally restores its saved participation. Restore network access first if the page reports an offline state.

To recover a generated-name session in another browser, enter the session code, select **Rejoin with handle**, enter the displayed name exactly, and select **Rejoin**. For learner or roster participation, reopen the original personal link.

If the host ended the session, use the next session's code or invitation. An expired or revoked personal link requires a replacement from its issuer.

---

## Students, groups, and classes

Source: https://openroom.app/docs/contexts/

Keep teaching context beside the relevant decks and prepare material for a learner or class.

### Create a context

In a Tutoring space, open **Students → Add student or group**. Choose **Individual** or **Small group**. In a Classroom space, open **Classes → Add class**.

Enter a **Name** and select **Save**. The remaining context fields are optional. Use them to record the learner's level, goals, and teaching background in concise terms.

The context appears beside that person's or class's decks. Open its **Edit** action to update it, then save. Agents connected to your workspace can read this information when preparing material.

### Create material for the context

Open the student's, group's, or class's Library and choose the intended folder. Select **New deck** to create a deck associated with the selected context.

The association carries into sessions started from that deck. It provides the connection needed for learner records, personal access links, and follow-up work. A deck created elsewhere can be taught without a learner context; choose the relevant context deliberately when creating material for named learners.

### Use sample lessons

Select **Sample lessons** from the context's Library. Filter by lesson language and level, then open the chosen lesson. Its copy appears as an editable deck in the current place.

Read its slides, questions, teacher notes, and homework. Replace names or examples where appropriate, confirm its answer keys, and preview its presentation before starting.

### Set teaching languages

Open **Space settings** or the context panel's **Set language** link. Select **Students’ language**, then **Teaching**, and save the language pair.

The first selection narrows the supported teaching languages. Changing it may clear an incompatible teaching selection. This pair drives dictionary lookup. The learner's interface-language selector separately controls the labels on their own page.

### Prepare the next lesson

Read the previous private **Next step** in the context panel. Open Notes for the relevant lesson to review outcomes and homework. Select **Review learner work** for submitted writing and voice responses.

In a context-linked deck, open the editor's **Notes** pane to find **Practice to revisit** and **From learner feedback**. Inspect an item before copying it into the new deck. The [review instructions](https://openroom.app/docs/review/#bring-selected-work-into-the-next-deck) explain which material becomes visible when copied.

### Manage access and removal

Use **Student access links** to create individual learner credentials. For a group or class, create a separate named learner link for each person whose work should remain separate.

Move a context to Trash through its management action when it is no longer in active use. Restore it before issuing new learner links. Review the browser confirmation carefully before permanent deletion; the context owns learner work and related access.

---

## Issue and replace learner links

Source: https://openroom.app/docs/learner-links/

Give each learner private access to their work and preserve identity when replacing a link.

### Create a link

**Required:** editor or owner access to the context's space.

1. Open the student's or class's Library and expand **Student access links**.
2. Select **Create link**.
3. Choose the **Learner**. For a new member of a group, choose **New learner** and enter their **Display name**.
4. Choose **Expires**. The default is 180 days.
5. Select **Create link**.
6. On **Copy this link now**, select **Copy link** and send it to the intended learner through your usual communication channel.
7. Select **Done** after storing or sending it.

The complete link is shown once. If clipboard access fails, select the displayed address and copy it manually before leaving the page.

### Explain what the learner receives

The link opens the learner's page containing their lesson outcomes, assigned homework, practice, writing or voice responses, and published feedback. For an identified live lesson, it also proves that person's identity within the associated context.

Each group member should use their own link. Their writing, recordings, feedback, and practice progress stay associated with that learner. Common outcomes and tasks assigned to everyone are shared within the context.

Possession of the link grants access. Ask learners to keep it private, especially on a shared computer. The issuer controls the display name and expiry.

### Replace a lost link

Create another link and select the **same learner** from the learner selector. Copy and send the replacement. Then revoke the old link if it is lost or no longer trusted.

Choosing the existing learner preserves their writing and practice history. Choosing **New learner** creates a separate identity, even if you type a similar name.

### Revoke or renew access

In **Learner access links**, find the link by learner, prefix, and expiry. Select **Revoke** and confirm. Further requests through that link are denied.

An expired link is renewed by creating a replacement for the same learner. A context supports at most 10 active links. Revoke an unused active link before creating another when the limit is reached.

### Use named live participation

Set the deck's identity mode to identified through its prepared outline when the session should admit only linked learners. Start the deck from its real context. Learners can enter the live session after it starts, using their personal credentials.

The current named-join workflow uses a personal participant address. Combine the session's join code and the learner token from their issued link:

```text
https://join.openroom.app/?code=SESSION_CODE&link=LEARNER_TOKEN
```

Replace both placeholders and send the completed address only to that learner. Use the participant origin of your installation if it differs. The learner token is the `token` value in the lesson-page link issued by **Create link**; it begins with `orlnk_`. Keep that lesson-page link for ongoing homework and feedback. After a successful join, the participant page uses a credential limited to the live session.

A named roster invitation belongs to one live session and follows a separate entry path. Use [roster invitations](https://openroom.app/docs/participant/#join-with-a-roster-invitation) for a one-session attendance or voting group, and learner links for continuing teaching records.

---

## Write session Notes

Source: https://openroom.app/docs/notes/

Save outcomes and homework, keep teaching notes private, and record the next step.

### Open the session's Notes

After ending a session, continue to its Notes page. You can also return through the Library's **Write the notes** prompt or the Notes links on the deck or person's folder.

Notes belong to the session that was taught. Check the session title before editing.

### Write and save

| Field | Content and audience |
| --- | --- |
| Outcomes (one per line) | Short statements of what was achieved. Shared through learner links when the session has a learner context. |
| Next step | A private teaching reminder used when preparing the next session. |
| Tutor notes / Private notes | Private teaching observations, available to authorized colleagues in the space. |
| Homework | Published tasks and their learner recipients for this session. |

Enter outcomes on separate lines. Keep **Next step** actionable. Review the homework inherited from the taught deck, adjust its instructions or recipients, then select **Save notes** or **Update notes**.

![Session Notes form with shared outcomes, private next step and tutor notes, and the homework section](https://openroom.app/docs/images/session-notes.png)

*Outcomes are shared with learners; Next step and Tutor notes remain on the teaching side.*

Sessions without a learner context retain their Notes in the space. A context-linked session shares only its learner-facing fields and the tasks each learner is entitled to receive.

### Carry over notes from presenting

The live **Private notes** scratchpad is kept on the current device. After ending the session, its contents prefill the Notes form when appropriate. Save the form to store them with the session.

If saved Notes and separate local notes both exist, review **Notes on this device**. Select **Add to private notes** to append the local text, or **Download private notes** to keep a text copy.

### Use Notes as a presenter

A Presenter can read shared session Notes and keep **Notes on this device**. These local notes stay in that browser. Use **Download private notes** to export them. An Editor or Owner saves changes to the shared session record.

If your editing access is removed while the form is open, saving stops and the private scratchpad remains on the device. Download a copy before leaving. Ask a space owner to review your access if further shared editing is needed.

### Handle concurrent changes

If another tutor changes the homework while your form is open, the save reports a conflict. Copy your edits before reloading, review the latest assignments, then reapply the intended changes. Existing learner responses keep the instructions they were submitted against.

Trashed sessions show saved Notes as read-only. Restore the session to resume normal editing.

---

## Assign and revise homework

Source: https://openroom.app/docs/homework/

Prepare reading, writing, voice, and practice tasks for everyone or selected learners.

### Prepare tasks in a deck

Open the deck's homework document in the editor. Add prose and typed tasks. Give each task enough information to complete it independently after the lesson.

| Task | Preparation |
| --- | --- |
| Reading | Include the actual passage or instructions to read. |
| Writing | Enter a clear prompt and optional guidance. Learners submit written responses. |
| Voice response | Enter a speaking prompt and optional guidance. Learners record or upload a response. |
| Practice | Include the exercise and its answer key when it has one. Supported formats are choice, text, fill-the-gaps, matching, and ranking. |

Practice can reuse a question from the deck or an exercise selected from **Practice to revisit**. Check that option labels, accepted variants, pairs, and correct order are complete before teaching.

The session captures the deck version used at start. Its Notes page takes the prepared homework from that version for publication.

### Publish through Notes

Open the session's **Notes** page. Review **Homework** and adjust each task's title, reading or instructions, and optional guidance. You can add new reading, writing, or voice-response tasks here.

Select **Save notes** or **Update notes** to publish the assignment. Learners with valid links receive the tasks through their own page.

A session requires a learner context to publish learner homework. Each assignment supports up to 50 tasks.

### Select recipients

Every task initially uses **Everyone in this context**. For an individual assignment:

1. Open **Who receives this task?** for that task.
2. Choose **Selected learners**.
3. Select at least one learner.
4. Save the Notes.

Create personal learner links first so the intended people exist in the context. Each learner then sees common tasks plus the tasks assigned to them.

Recipient selection belongs to this session's assignment. The reusable deck can be used with another group without carrying the previous group's recipient list.

### Revise instructions or withdraw a task

Reopen Notes, edit the relevant task or recipients, and select **Update notes**. Use **Remove task** to withdraw it from the current assignment.

Earlier submissions retain their original task wording. Learners working from an older assignment may be prompted to load the updated exercise before submitting. Their already-entered answer remains visible while they decide how to continue.

Changing only private Notes keeps assignment recipients intact. If a concurrent edit prevents saving, copy your changes before reloading and checking the current assignment.

### Review the resulting work

Open **Review learner work** from the context's Library to review writing and voice responses. Practice results and corrections selected for reuse appear in a context-linked deck's Notes pane.

Use [published feedback](https://openroom.app/docs/review/) to guide a revision, then select the specific exercise or correction worth revisiting in the next deck.

---

## Review work and share feedback

Source: https://openroom.app/docs/review/

Read original submissions, publish corrections and audio comments, and choose material to revisit.

### Open a response

Open the learner or class Library and select **Review learner work**. Choose **Review response** beside the submission you want.

Read the original task alongside the learner's response. The task shown with a submission is the version used when that response was sent, including when the current homework has since changed.

Reviewing and publishing feedback requires editor or owner access to the context.

### Review writing

Enter the overall message in **Feedback**. To add a correction, select **Add correction** and complete:

- **Their words:** the wording you are discussing.
- **Suggested wording:** the proposed revision.
- **Why:** the explanation the learner should use next time.

Use **Remove correction** to discard an entry. A response can have up to 30 corrections. Keep corrections specific enough that the learner can apply them to their revision.

### Review a voice response

Play the recording beside its original task. Pause or seek to the moment you want to discuss, then select **Comment at …**. Write **Feedback at this point** for that timestamp.

Add an overall feedback message if needed. A recording can have up to 30 timed comments. Published comments let the learner seek directly to the relevant point.

Use the recording's download, trash, and restore actions according to the available access and retention window. Trashing a recording immediately stops normal playback; restoration is available for seven days within the recording's overall 90-day retention period.

### Save privately or publish

Select **Save draft** to keep the feedback private to the teaching side. Select **Share feedback** to publish it to the submitting learner. After editing previously published feedback, select **Share updated feedback** to publish the revision.

The learner reads published feedback in their **Feedback** tab. They can revise writing or submit another recording. Open the new submission to review its own response and task snapshot.

### Bring selected work into the next deck

Open a deck linked to the learner's context and select **Notes** in the task pane.

Under **Practice to revisit**, expand an exercise to inspect the learner's answer and the answer key. Select **Add as a slide** or **Add to homework** for that exercise. The copy retains its question format, options, and keys and can be edited independently. The learner's identity and submitted answer stay in the private review view.

Under **From learner feedback**, expand a correction and review its wording and explanation. Select **Add correction to deck** only when that text is appropriate for the deck's audience. The copied correction's wording and explanation become visible in the deck.

Review the inserted material on the canvas, then present or start the new deck normally. Each selection is explicit, allowing you to choose exactly what to revisit.

---

## Your lessons, homework, and feedback

Source: https://openroom.app/docs/learner/

Use your personal link to read lesson outcomes, practise, submit work, and review feedback.

### Open your page

Open the personal link supplied by your teacher. Keep it somewhere private so you can return to your work. The page shows the name assigned to your link.

Choose **English**, **Français**, or **Deutsch** from the interface-language selector. This changes the page's controls and messages; lesson content keeps the language used by your teacher.

Use the three tabs:

| Tab | Contents |
| --- | --- |
| Lesson | Lesson outcomes, materials, reading, writing, and voice tasks. |
| Practice | Exercises assigned to you and your saved practice progress. |
| Feedback | Your teacher's published feedback on your submissions. |

In a group, each person should use their own link. A replacement link for the same learner keeps that person's earlier work.

### Read and write

Open **Lesson** and read the outcomes, materials, and assigned instructions. For a writing task, enter your response and select **Save**. Wait for **Saved** before leaving.

You can return to the task, revise the text, and save another response. The teacher reviews the submitted wording alongside the task instructions that applied to it. Writing responses support up to 10,000 characters.

If saving fails, keep the page open and retain a copy of your text. Check the error, restore connectivity, and retry. If the assignment changed, load its current instructions before submitting a new answer.

### Practise

Open **Practice** and complete the current exercise. Select options, fill blanks, match pairs, reorder items, or type your answer. Select **Check** to reveal the assessment or self-check information.

Use **Good** or the confidence action when you are satisfied with the response. Use **Again** when you need to practise it again. **Try again** starts another attempt at the exercise. Wait for the saved state so your progress survives a reload.

For an open answer without a fixed key, assess your confidence using the provided self-check action. A teacher-authored answer key is used only where the exercise includes one.

If a save fails after checking, retry from the retained answer. If the task has changed, use the displayed refresh action to load the new exercise. A background refresh keeps the question and answer you are currently working on until you deliberately replace them. If the teacher withdrew the exercise, continue to the next available task.

### Send a voice response

1. Open the voice task in **Lesson** and read its prompt.
2. Choose the recording action and allow microphone access, or choose an audio file.
3. Record your answer and stop. The maximum duration is five minutes.
4. Listen to the preview. Record again if needed, or download a personal copy.
5. Send the response and wait for confirmation.

Source audio files can be up to 20 MiB. Conversion to the submission format happens on your device. Use the file choice if the browser cannot access your microphone. Leaving the Lesson tab or hiding the page stops microphone capture.

A failed upload keeps the preview available. Retry the same submission rather than recording it again solely because the response was lost. Each task supports up to 10 retained recordings, including recordings in recoverable trash.

Use the recording's trash action to remove a response from playback. You can restore it within seven days, subject to the 90-day overall audio-retention period.

### Read feedback and revise

Open **Feedback** to read shared comments and corrections. For a recording, select a timed comment to listen at that point. Draft feedback appears only after your teacher shares it.

![Learner Feedback tab showing a published comment, original wording, suggested wording, and explanation](https://openroom.app/docs/images/phone-feedback.png)

*Use the suggested wording and explanation when preparing a revision.*

Return to **Lesson** to revise your writing or make another recording. A new submission lets the teacher review the revised work separately.

### Recover access

If the link has expired or was revoked, ask the teacher for a replacement for your existing learner identity. If the page shows another person's name, stop entering work and open your own link.

When switching personal links on a shared device, open the complete intended link and check its displayed name. Each link selects its own learner data and form state.

---

## Results, exports, and workshop recaps

Source: https://openroom.app/docs/results/

Read saved responses, download data, and select material for a shareable recap.

### Download live results

Open **Session menu** in the presenter and choose a download:

| Download | Contents and use |
| --- | --- |
| Download JSON | Structured session results for analysis or processing. |
| Download counts (CSV) | Aggregate results in a spreadsheet-friendly file. |
| Download responses (CSV) | Individual answers, available with named-response export access or for a roster session. |

Downloads reflect the responses available at that moment. Download again after the final question for a complete copy. Individual-response exports can contain participant names; free-text answers can also identify a person regardless of the session's identity setting.

Keep session control links private. Share a reviewed export or recap with the intended recipients.

### Open saved results

For an account with **Saved session archives**, **End session** captures a retained results file. Individual responses are included when the owner also has the relevant export entitlement at capture time. Finish explicitly and check the saved file when you need a retained archive.

Open the deck in the Library and follow its **Saved results** link. The results document shows the captured questions, answer labels, numerical summaries, and visible text responses.

- **Download report** saves a readable HTML file that opens in a browser.
- **Download individual responses** saves the retained response CSV, when included in the archive.
- **Download data** saves the structured JSON.
- **Open deck** returns to the source deck's editor.

The readable report excludes hidden entries. Data and individual-response downloads can contain hidden entries and names. Inspect those files before sharing them.

Saved results remain available for **90 days**. Download a copy for longer retention. Existing captured files remain accessible after a plan downgrade until they expire; access to a shared space still requires current membership. An expired file or removed space membership produces **Saved results unavailable**.

### Prepare a workshop recap

1. Open **Session menu → Prepare workshop recap**.
2. Enter the recap title.
3. Select the results, discussion contributions, and questions to include. Review the actual text before selecting it.
4. Add a **Discussion summary** and **Shared follow-up** as needed.
5. Review the recap, then download HTML for reading or JSON for further processing.

The selection starts empty. Select only material suitable for the recipients. A recap can combine result summaries with selected contributions without including every submission.

If the source changes while preparing the recap, refresh the available content and select the entries again. Keep the title, summary, and follow-up under review as well. These editorial fields are local to the recap preparation page; download the finished file before leaving it.

Recap source data is available only before the live response purge. Prepare and download the recap promptly after the workshop. The title permits 160 characters; the discussion summary and shared follow-up permit 10,000 characters each.

### Keep teaching records separately

Use [Notes](https://openroom.app/docs/notes/) for outcomes, private tutor notes, and assigned homework. Use saved results for captured live responses. Use a recap for a deliberately selected document to share. Each has its own visibility and retention rules, described in [privacy and limits](https://openroom.app/docs/limits/).

---

## OpenRoom Desktop and local files

Source: https://openroom.app/docs/desktop/

Open, save, present, and synchronize portable .openroom decks.

### Open a deck

Install the OpenRoom Desktop build supplied for your computer. Open the application, then choose **File → Open** or open an `.openroom` file from your file manager. **File → New** starts a blank deck.

The deck editor uses the same slide, question, design, and presentation tools as the browser editor. The Desktop **File** ribbon adds local file and synchronization controls.

An `.openroom` file contains the deck and its packaged resources. Copy or send the file to another computer to continue editing there. External links keep their original addresses.

### Run Desktop from the repository

For the current source build, install dependencies and build the repository, then start Desktop:

```sh
bun install
bun run build
bun run desktop
```

The launcher builds the Desktop shell, applies local database migrations, and starts or reuses the local server. It prints the server and participant addresses. Keep it running while using that local environment. Devices on the same network can use the printed participant address when the network permits access.

Repository launches use local configuration and storage. Use the account and server intended for your teaching material, and check the printed origin before signing in or sharing a join address.

### Save your work

| Control | Action |
| --- | --- |
| Save | Write changes to the current file. Choose a destination when saving a new file. |
| Save as… | Save a copy at a chosen path. |
| Open… | Choose another `.openroom` file. |
| Show in folder | Reveal the saved file in the operating system's file manager. |

Use **Save** before closing or moving a file. Follow the unsaved-change prompt when closing a changed deck. If **Unsaved decks found** appears after reopening Desktop, choose **Recover** to reopen the recoverable work or **Discard** to remove that recovery copy. Save a recovered deck to retain it as a normal file.

Keep one writer in charge of a local file. A file already open elsewhere can be locked against writes; finish or close the other editing session before retrying.

### Work offline

Open, edit, save, and present local decks while offline. Embed the pictures, audio, and extracted PDF pages needed for the lesson and test the file with the network disconnected before teaching offline.

Cloud synchronization, live participant sessions, stock search, web embeds, external media, and model-provider requests require their respective online services. **Present** is useful for rehearsing or displaying a local deck on the same computer.

### Save a file to a workspace

1. Sign in to OpenRoom through the system browser when prompted.
2. Open **File → Save to workspace…**.
3. Choose the space and folder.
4. Select a student or class only when the deck belongs to that context; otherwise keep **No student**.
5. Confirm and wait for the deck and its resources to finish uploading.

The local file becomes linked to that cloud deck. Use **Open online** to open its workspace copy. Shared-space roles apply to cloud reads and writes.

### Synchronize changes

Use **Sync now** for a linked file. Keep the network available until synchronization finishes.

If both the file and its online copy changed, review the conflict before selecting a resolution:

- **Use online copy** loads the current online content into the file.
- **Keep this file** uses the local content for the cloud update.

Save a separate copy first if you need to retain both variants. A conflict requires an explicit choice; retrying a stale write does not resolve it.

### Start an online session

Select **Start session** from the local deck. Sign in and choose a cloud location if needed. OpenRoom uploads the material required for the session before opening participation.

Continue with the same presenter and participant controls described in [running a live session](https://openroom.app/docs/live-session/). End the session before returning to local editing when the audience has finished.

### Prepare with an agent

Open the Desktop **Agent** pane to work with your own model subscription or provider key. The agent works against the deck open in Desktop. See [Desktop agents](https://openroom.app/docs/desktop-agents/) for sign-in, attachments, conversations, and provider settings.

---

## Prepare a deck with a Desktop agent

Source: https://openroom.app/docs/desktop-agents/

Connect your own model account, attach source material, and review changes in the editor.

### Choose an agent

Open a deck in OpenRoom Desktop and open **Agent**. Use the agent settings to choose **Claude**, **ChatGPT**, or **API key**.

| Choice | Requirement |
| --- | --- |
| Claude | The local Claude harness and a signed-in account with access to it. Follow the installation or sign-in action if offered. |
| ChatGPT | The local Codex harness and a signed-in account with access to it. Follow the installation or sign-in action if offered. |
| API key | Your own account and key for a supported provider. |

Agent turns run on your computer through the selected harness. Model requests use your subscription or provider account. Your provider's limits and billing apply.

The in-app conversation is available in Desktop. For browser decks, use an [external agent connection](https://openroom.app/docs/agents/).

### Configure a provider key

Select **API key**, then choose a provider: OpenAI, Google, Anthropic, Mistral, Groq, OpenRouter, or Cloudflare. Enter the key and select **Save key**. Cloudflare also requires the account identifier shown in its configuration form.

Choose a model from the available list, or retain the default. Model availability depends on the provider and account. Change provider or model before starting the next request.

Keys saved through Desktop are stored in the operating system's keychain and sent to their selected provider. Use **Remove** to delete a saved key. A key supplied by the launch environment is marked **From environment**; change that environment configuration to replace or remove it.

### Give a concrete preparation request

Describe the audience, objective, available time, and material to use. For example:

> Prepare a B1 French lesson on explaining a missed connection. Use the attached passage. Include a short reading, three comprehension questions, a gap exercise on past tenses, and a writing task. Keep each slide readable on a phone.

Select **Send**. Answer any questions the agent presents. Use **Stop** to interrupt a running turn. Review the deck as changes appear in the editor, then refine the request or edit the content directly.

Check factual statements, task instructions, accepted answers, reveal order, and homework before presenting. Use **Present** to rehearse and save the file when satisfied.

### Add reference material

Use **Attach files**, drag a supported file into the pane, or paste an image. Attached items appear as chips; remove a chip before sending to exclude it from that request.

Use **Reference folder** when the agent needs to read files from a local directory. Choose a folder containing only the material needed for the task.

Desktop gives the local agent access to the selected material. Temporary attachment copies belong to the conversation's working directory; referenced folders are read in place. Original school documents stay outside OpenRoom's servers. The selected model provider may receive content used in model requests, under that provider's account terms. Check the requested material before sending.

### Manage conversations

Use **Chats for this deck** to reopen a conversation. Select **New chat** for a new preparation task. Changing the agent host begins a new conversation.

Conversation history is stored locally. Temporary attachment workspaces are cleaned up with the conversation lifecycle; keep original files in your own folders. Reattach needed material when beginning a fresh conversation.

When available, **Open in Codex** continues the selected conversation in the signed-in Codex application. Check the active deck and working directory before asking for further changes.

### Recover from a failed turn

Check the error in the pane and the provider configuration. For an expired login, sign in again. For provider quota or rate limits, wait or choose an available model/account. For a missing attachment, attach it again.

Inspect the deck before retrying: a failed or interrupted turn may already have completed some edits. Save a useful intermediate file or use editor history before requesting the remaining changes.

---

## Use OpenRoom in PowerPoint

Source: https://openroom.app/docs/powerpoint/

Embed OpenRoom slides, connect the task pane, rehearse, and run participation alongside a presentation.

### Requirements and availability

The current PowerPoint integration is a **local preview build**. Use the supplied manifests with a supported PowerPoint installation and the matching OpenRoom server. Native sign-in, cross-window communication, slide-show activation, and save/reopen behavior require verification on the PowerPoint installation used for the event.

Allow time for a rehearsal on that computer. Keep the OpenRoom task pane available as the manual control surface.

### Install the local Mac preview

With the repository and its dependencies installed, run this command from the repository root:

```sh
bun run office:install
```

The installer sets up Microsoft's localhost development certificate, builds and serves the apps at `https://localhost:3443`, and installs the two local manifests. Restart PowerPoint, open a presentation, and choose **Home → Add-ins**. Open **OpenRoom for PowerPoint** for the task pane and **OpenRoom Slide** for an embedded slide. The task pane is also available from **Home → OpenRoom**.

Keep the server command running. On later runs, use:

```sh
bun run dev:office
```

This local server is reachable only on the Mac. Use a reachable deployment for participants on other devices. The local sign-in option is **Sign in with demo account**, with username `alice` and password `demo`. These credentials apply only to that local preview.

The development certificate lasts 30 days. Rerun the installer to renew it. To remove the preview, delete `openroom-taskpane.xml` and `openroom-display.xml` from `~/Library/Containers/com.microsoft.Powerpoint/Data/Documents/wef`, then restart PowerPoint. Presentations and local data remain in their own locations.

### Connect the task pane

Open **OpenRoom for PowerPoint**, select the sign-in action, complete sign-in in the opened browser, and approve the connection for the intended account. Return to PowerPoint after the connection succeeds.

Use the same server address throughout sign-in and presentation. If the pane reloads and asks to reconnect, reconnect before resuming the existing session. Revoke an old connection in OpenRoom **Settings → Connected apps** when needed.

### Insert an OpenRoom slide

Choose a space, deck, and slide in the embedded picker. Alternatively:

1. Open a cloud deck in OpenRoom's editor.
2. Select the slide.
3. Select **Home → Copy embed code**. Wait for pending changes to save.
4. Paste the code into the PowerPoint add-in's embed-code field.

For a local `.openroom` file, [save it to a workspace](https://openroom.app/docs/desktop/#save-a-file-to-a-workspace) first.

The code identifies a particular deck version and slide. The preview uses that content, including slide design, questions, media, freeform objects, and detail slides. Choosing a slide in the task pane also prepares it for the next **OpenRoom Slide** insertion.

Size and position the content add-in on the native PowerPoint slide, then preview it in Slide Show. Keep essential content clear of PowerPoint overlays.

### Rehearse an activity

Use the selected-slide rehearsal controls to try opening, closing, revealing, reopening, and resetting a question. Rehearsal uses local sample answers. Check result labels, reveals, timers, and the fit of the embedded display.

Rehearse the complete presentation in Slide Show as well. Test the connection and the manual **Show selected slide** action on the actual computer.

### Start one audience session

Select **Start session** in the connected task pane. The session gathers embedded OpenRoom slides in native presentation order. The selected slides must belong to one space and use compatible context and identity settings.

The session captures that composition. Finish selecting and arranging activities before starting. To include later additions, replacements, or reordered activities, end the current audience session and start a new one.

Share the resulting join link or code. Keep the signed-in task pane open. In supported Slide Show operation, activating an embedded OpenRoom slide presents it to the audience and opens its activity. Repeated activation of the current slide preserves a deliberately closed question. Returning to another previously asked question reopens it with the existing answers.

### Use the companion controls

If automatic activation is unavailable, select the relevant PowerPoint slide and use **Show selected slide** in the task pane. Run the audience **Stage** in a browser when a separate projected display is needed.

Use the task pane's question and session controls to close, reveal, and end participation. After a temporary connection failure, reconnect and resume the existing session. Check the session code before starting another audience.

---

## Account, billing, and connected apps

Source: https://openroom.app/docs/account/

Manage sign-in, plan access, subscriptions, personal tokens, and external connections.

### Manage your account

Open **Settings** to review the signed-in account. Use the same account for the workspace, Desktop connection, and integrations that should share your decks. Sign out before leaving a shared computer.

Space ownership and membership determine access to shared material. A learner access link and a participant invitation each open their own limited destination; use account sign-in for workspace administration.

### Review available plans

Select **Settings → Open billing**. Review the current plan and the available offers. Each offer states its price, currency, billing interval, and included capabilities. Use the values displayed there for the active installation.

| Capability | Access it provides |
| --- | --- |
| Saved session archives | Capture ended-session results for the archive retention period. |
| Named response exports | Download individual responses, with the identity available for the session. |
| Shared brand kits | Store and reuse a space's visual design. |
| Shared spaces | Invite colleagues to a shared Library and work together. |
| Connected workflows | Use entitled external account integrations. |
| Named session invites | Issue individual roster invitations for one session. |

For shared-space work, the relevant owner entitlement supplies paid features. Invitees use their assigned space role; they do not each need a separate licence for that shared workspace.

### Start or change a subscription

Select **Choose plan**, then follow the secure checkout link. Review the checkout's billing frequency, tax, renewal, trial, and payment terms before completing it.

Return to billing after checkout. Entitlements update after payment information is verified. Use **Refresh billing** if the page still shows the previous state. An unfinished checkout offers continuation or cancellation of that pending checkout.

Checkout requires the installation's configured billing service and approved offers. A **Sandbox** indication means the checkout uses the test environment.

### Manage an existing subscription

Select **Manage billing** and open the prepared customer-portal link. Use that portal for supported subscription changes, payment details, and invoices. Return to OpenRoom and refresh billing afterward.

The status may show **Active**, **Trial**, **Payment needs attention**, **Paused**, or **Ended**. Follow the payment action when attention is required. New paid operations use the current verified entitlement. Existing captured archives remain available until expiry; collaboration already enabled for a session remains subject to current membership and connection access.

### Create and revoke personal API tokens

1. Open **Settings → Connect an agent (MCP) → Create token**.
2. Give the token a label identifying its client or purpose.
3. Select **Create token** and copy the secret immediately.
4. Store it in the intended client's secret configuration.

The full token is displayed once. The token list shows its label, prefix, creation time, and last use. Search the list to find a particular token. Open its actions menu and select **Revoke token** to stop it immediately, then update any client that used it.

A personal token carries your workspace authority. Treat it as an account secret. Use a separate labelled token for each client so that one integration can be revoked independently.

### Manage connected apps

Review **Connected apps** in Settings. Revoke a connection that is no longer needed or belongs to an untrusted client. Revocation stops that connection and host credentials issued through it. Reconnect through the app's consent flow if you need to use it again.

Personal API tokens and connected-app authorizations are managed separately. Revoke the credential actually used by the client.

---

## Connect an external agent

Source: https://openroom.app/docs/agents/

Author decks and manage your work through an MCP client using your OpenRoom account.

### Choose the connection

OpenRoom provides an MCP server for compatible agent clients. Use the server URL shown in **Settings → Connect an agent (MCP)** for your installation. The hosted service uses `https://openroom.app/api/mcp`.

| Connection | Use it for |
| --- | --- |
| Hosted MCP with account consent | A client that supports OpenRoom's browser sign-in and authorization flow. |
| Hosted MCP with a personal token | A client that accepts an HTTP server URL and Authorization header. |
| Local stdio MCP | An agent working with the open Desktop file or a local `.openroom` file. |

Your agent runs in your chosen client. OpenRoom receives the resulting deck and account operations. Supply source documents to your own agent in accordance with their handling requirements.

### Connect with account consent

In a compatible client, add the MCP URL as a connection. Follow the browser sign-in flow, review the requested access, and approve the intended account. Return to the client and refresh its available tools.

Client support and account requirements vary. For a client that requests a token header instead, use the token procedure below. Manage consent-based connections in [Connected apps](https://openroom.app/docs/account/#manage-connected-apps).

### Connect with a personal token

Create a [personal API token](https://openroom.app/docs/account/#create-and-revoke-personal-api-tokens), then configure:

```text
Server URL: https://openroom.app/api/mcp
Authorization header: Bearer YOUR_PERSONAL_TOKEN
```

Use your installation's origin if it differs. In clients that ask for the complete header, enter `Authorization: Bearer YOUR_PERSONAL_TOKEN`. Keep the secret in the client's protected configuration.

Settings includes **Copy command** for Claude Code and **Copy URL** / **Copy header** helpers for compatible clients. Copy the command offered by the current app rather than adapting an old configuration by hand.

After connecting, ask the agent to read its OpenRoom instructions and list the spaces available to your account. Confirm the destination before asking it to create or change a deck.

### Prepare and revise a deck

A useful request includes the destination, audience, teaching objective, source material, and desired output. For example:

> In the French tutoring space, create a deck in Camille's folder for a 30-minute B1 lesson about travel disruptions. Use my attached passage, include comprehension and past-tense practice, and add a writing task. Keep the source wording and explain any changes you make.

Open the resulting deck in the editor. Check slide fit, answer keys, accepted variants, and follow-up work. For a revision, identify the existing deck and explain the changes so the agent can update the correct file.

The MCP server supplies the current tool descriptions, argument contracts, and validation errors directly to the client. Have the agent use those descriptions when saving, resolving a version conflict, starting a session, or recovering an operation. They are the authoritative reference for the agent surface.

### Work on a local file

Configure a stdio client to launch the repository's CLI with `mcp`; see [CLI setup](https://openroom.app/docs/cli/#run-the-cli-from-a-checkout). Add the path to an `.openroom` file when working headlessly.

The local connection first uses a running Desktop instance. Otherwise, an explicit file path opens the local file backend; without either, the CLI uses the configured hosted backend. Confirm the active document before requesting edits. A local file lock can require closing another writer before saving.

For authenticated cloud work, configure the direct HTTP MCP connection with account consent or a personal token as described above. The stdio hosted fallback supplies public server discovery. `OPENROOM_ORIGIN` selects its server origin.

Keep original reference documents in your own storage. Review and save the resulting deck before sharing it with learners or starting participation.

### Resolve access failures

For an authentication failure, check the origin and token or repeat the consent flow. For a permissions failure, confirm current membership and role in the destination space. For an entitlement message, review the owner's current plan.

Recoverable deletion uses Trash. Permanent deletion ends in a short-lived browser confirmation, where the signed-in account reviews the item. Follow that confirmation only when you intend to remove the item permanently.

---

## Command-line and file workflows

Source: https://openroom.app/docs/cli/

Validate files, revise cloud decks safely, control a session, and find the authoritative API contracts.

### Run the CLI from a checkout

The current CLI is supplied in the OpenRoom repository. Install repository dependencies and build its packages from the repository root:

```sh
bun install
bun run build:packages
node packages/cli/dist/cli.js --help
```

The examples below use `openroom` as shorthand for `node /absolute/path/to/OpenRoom/packages/cli/dist/cli.js`. Use that full command, or configure a shell alias to it. Run file-related commands in the folder where you want their output.

Use `--help` for the current command list and `--json` for structured output. Exit codes are **0** for success, **1** for validation or command failure, and **2** for usage errors.

### Start with a small session file

```sh
openroom init lesson.yaml
openroom validate lesson.yaml
openroom preview lesson.yaml
```

`init` writes a starter file. An existing file requires `--force` to replace it. `validate` reports errors with locations. `preview` prints host and participant representations so you can check the available content and answer visibility.

This compact format is useful for simple questions. For full decks with slides, layouts, teaching activities, and advanced interactions, use the typed outline format:

```sh
openroom outline validate plan.yaml
```

Keep YAML outline files separate from packaged `.openroom` files. An `.openroom` file is the portable Desktop package, with its manifest and embedded resources.

### Read and revise a cloud deck

Create a personal token in Settings. The examples use `OPENROOM_TOKEN` for a token already stored in your local environment and `DECK_ID` for the target deck identifier. Replace the origin when using another installation.

```sh
openroom deck get DECK_ID --url https://openroom.app --token "$OPENROOM_TOKEN" > plan.yaml
openroom deck versions DECK_ID --url https://openroom.app --token "$OPENROOM_TOKEN"
openroom outline validate plan.yaml
openroom deck save DECK_ID --file plan.yaml --base 3 --url https://openroom.app --token "$OPENROOM_TOKEN"
```

Edit the downloaded file between reading and validating it. Replace `3` with the version you actually read. The save validates the outline and creates a saved version when the content changes. An explicit base version protects against overwriting someone else's intervening change.

For **E_VERSION_CONFLICT**, read the latest version, compare it with your edited file, reconcile the changes, and save against that latest base. Keep a local copy of your intended changes during reconciliation.

Use `deck get DECK_ID --version N` to read a particular saved version. The normal text output is YAML suitable for redirection; `--json` wraps the result for scripts.

### Exchange working drafts

Use `deck draft get`, `deck draft put --file plan.yaml --base N`, and `deck draft discard` with the deck ID, origin, and token. A working draft can contain incomplete or invalid text. Saving a validated deck version is a separate operation.

Coordinate draft changes with anyone currently editing the same deck. After a draft upload, open the editor and review the content and validation state before starting a session.

### Start and control a session

```sh
openroom deck start DECK_ID --url https://openroom.app --token "$OPENROOM_TOKEN" --json
openroom session facilitate SESSION_CODE --url https://openroom.app --token "$OPENROOM_TOKEN"
openroom session status
```

Use the session code returned by the start command in the second command. `deck start` reports the launched session; `session facilitate` attaches the CLI to it and stores its control state in the current directory. Check a returned start warning before assuming participation is open.

The following operations use that attached session:

| Task | Commands |
| --- | --- |
| Open, close, or reveal a question | `session open ID`, `session close ID`, `session reveal ID` |
| Navigate | `session advance`, `session outline-next`, `session outline-previous`, `session outline-goto STEP_ID` |
| Add a prepared slide | `session outline-insert step.json --after STEP_ID --show` |
| Run peer instruction | `session revote ID`, `session undo-revote ID` |
| Freeze or resume participation | `session freeze`, `session unfreeze` |
| Change the live interface theme | `session theme default` (also `chalkboard`, `paper`, `projector`, `sherbet`) |
| Moderate an entry | `session hide INTERACTION_ID PARTICIPANT_ID`, `session unhide INTERACTION_ID PARTICIPANT_ID` |
| Manage groups | `session group-set group.json`, `session group-remove GROUP_ID` |
| Transfer presenter control | `session handoff FACILITATOR_ID`, `session recover` |
| Finish | `session end` |

Use identifiers from the current outline and session state. Presenter and membership requirements apply to CLI commands just as they do in the browser.

The local `.openroom.json` state file contains session credentials. Keep it private and out of version control. Use a different working directory for another session to keep the control state separate.

### Issue named roster invitations

Roster administration uses the live-session API. Prepare a deck with roster identity, start it using an entitled account, and retain its session code and host capability. Use the current session's host token in these requests.

| Request | Purpose |
| --- | --- |
| `POST /api/sessions/SESSION_CODE/roster/seats` with JSON `{"displayName":"Alex"}` | Create a named seat and obtain its one-time displayed invitation token. |
| `GET /api/sessions/SESSION_CODE/roster/seats` | Read the named seats and their redemption/revocation state. |
| `DELETE /api/sessions/SESSION_CODE/roster/seats/SEAT_ID` | Revoke the invitation for that seat. |

Send the requests with `Authorization: Bearer HOST_TOKEN` and a JSON content type for creation. Keep the returned token private. Form the participant address using `https://join.openroom.app/?code=SESSION_CODE&invite=INVITATION_TOKEN`, replacing the origin for your installation.

The roster supports 200 active seats. Names are normalized to single spaces and limited to 64 characters. Send each person their own invitation. Keep the seat identifier so an invitation can be revoked later.

### Export results

```sh
openroom results
openroom export --format csv --out counts.csv
openroom export --format json --out results.json
openroom export --format ballots --out responses.csv
openroom session recap --selection selection.json --format html --out recap.html
```

Individual-response export requires the relevant entitlement. Build a recap selection from the current available entries and review the resulting document before sharing. Live retention limits still apply.

### Connect stdio MCP

Configure the client with the CLI executable and its arguments:

```sh
openroom mcp
openroom mcp /absolute/path/to/lesson.openroom
```

Use one of these forms for the intended backend. The process communicates over standard input and output; let the MCP client manage it. See [external agent setup](https://openroom.app/docs/agents/) for backend selection and access.

### Use the API reference

`openroom api METHOD /api/... --url ORIGIN --token TOKEN` sends an authenticated control-plane request. Supply a body through `--file request.json` or `--body` as needed.

Use the deployed [OpenAPI document](https://openroom.app/openapi.json) for routes and request/response contracts, and the [MCP endpoint](https://openroom.app/api/mcp) through an MCP client for its tool descriptions. These are generated with the running application. The repository's [agent guide](https://github.com/youtiger/SlidoCompetitor/blob/main/docs/AGENT.md) supplies integration background when that repository is available to you.

Use account credentials for account work, the session capability for its live controls, and the appropriate learner credential for learner access. A permanent deletion request produces a browser confirmation that must be completed by the signed-in account.

---

## Privacy, retention, and limits

Source: https://openroom.app/docs/limits/

Check who can access each kind of material, how long it remains available, and the supported size limits.

### Access boundaries

| Material or credential | Access |
| --- | --- |
| Space and its folder tree | Current members, according to owner, editor, or presenter role. |
| Personal API token | The issuing account's control-plane authority. Store it as an account secret. |
| Live host, stage, and remote links | Their designated role in one live session. Keep host and remote links with the facilitators. |
| Learner access link | One named learner's records within one context, including assigned tasks and published feedback. |
| Roster invitation | One host-named seat in one session. |
| Uploaded deck media | Anyone possessing its asset URL. |
| Learner voice work | The submitting learner and authorized workspace reviewers, through authenticated access. |

A space shares one Library tree. Put material for a different membership group in a separate space. A copied download is governed by where you store or send it afterward.

### Private and shared teaching text

| Field | Intended visibility |
| --- | --- |
| Slide presenter notes | Host-side preparation and teaching surfaces. |
| Live Private notes | The current browser's scratchpad until saved into the teaching record. |
| Notes: Tutor notes and Next step | Authorized workspace users. |
| Notes: Outcomes | Learners in the context. |
| Homework assigned to everyone | Learners in the context. |
| Homework assigned to selected learners | The selected learner identities. |
| Writing, voice work, practice progress | Its learner and authorized reviewers. |
| Feedback draft | Authorized reviewers. |
| Shared feedback | Its learner and authorized reviewers. |

Check outcomes, question text, homework, and feedback for private information before sharing. Selecting a learner response for a new teaching slide can expose its wording to the future audience; edit that wording deliberately.

### Live-session retention

The live retention clocks begin when the session ends, including an automatic end after **12 hours of inactivity**.

| Time after ending | Available data |
| --- | --- |
| First 30 minutes | Live individual responses and participant records remain available for authorized export and recap preparation. |
| After 30 minutes | Individual ballots and participant records are purged. Aggregate results and anonymized text remain temporarily available. |
| After 24 hours | The live session's stored state is deleted. |

Download needed response data promptly. Anonymized text can still identify a person through its wording; review it before sharing.

Eligible **saved results archives** are captured on session end and retained for **90 days**. Download a copy for longer retention. A retained archive's contents are fixed at capture; a later plan upgrade affects future paid operations.

Decks, Notes, assigned homework, and learner work use their own durable records and lifecycles, separately from the live-data retention clock.

### Learner recordings and links

Voice work is retained for **90 days**. A trashed recording can be restored for **7 days**, within its original retention period. Up to **10 retained recordings per learner and task** count toward the limit, including recordings in Trash.

Each context supports **10 active learner links**. The default link lifetime is **180 days**; choose the expiry shown in the creation form. Replace a link by selecting its existing learner identity to preserve that learner's work.

Revocation or expiry prevents further access through the affected link. A replacement link and a space invitation are separate credentials with separate destinations.

### Content and file limits

| Item | Limit |
| --- | --- |
| Choice options | 2–10 |
| Ranking options | 2–6 |
| Scale range | Maximum minus minimum: 2–10 |
| Short text response | 200 characters by default; configurable up to 500 |
| Accepted short-text answers | 20 |
| Gaps in one exercise | 1–8 |
| Active roster seats in one session | 200; each name up to 64 characters |
| Slide masters in a deck | 20 |
| Master content margin | 3%–12% |
| Uploaded media or one packaged resource | 20 MiB |
| Resources in an `.openroom` package | 100 files; 50 MiB combined |
| Source PDF for Desktop page extraction | 100 MiB; extracted resource must fit the package limit |
| Homework tasks in a record | 50 |
| Homework title | 300 characters |
| Homework prompt or guidance | 2,000 characters |
| Reading assignment text | 5,000 characters |
| Learner writing | 10,000 characters |
| Voice response | 5 minutes and 20 MiB |
| Feedback message | 10,000 characters |
| Corrections or timed voice comments | 30 per feedback document |
| Recap title | 160 characters |
| Recap discussion summary or follow-up | 10,000 characters each |

Validation messages identify fields requiring correction. Splitting long material into readable slides or separate assignments is often preferable to reaching a maximum size.

### Connectivity and device requirements

Live participation and synchronization require an internet connection to the active installation. Browser microphone access requires permission and a secure origin. Clipboard, fullscreen, pop-up, and media playback controls can require an explicit gesture or browser permission.

Desktop can present embedded local material offline. Test all external resources, audio output, and projected displays on the teaching computer. Agent requests require access to the selected model provider; dictionary lookup and stock images require the configured services.

### Terminology

| Term | Meaning |
| --- | --- |
| Deck | The editable teaching or presentation file. |
| Space | A shared folder tree and its membership boundary. |
| Folder | A location within a space. |
| Context | The teaching information associated with a student, group, or class. |
| Session | One live occurrence started from a deck. |
| Stage | The audience display. |
| Notes | A session's saved outcomes, private teaching notes, and follow-up work. |
| Draft | Working deck content, which can still be incomplete. |
| Version | Saved, validated deck content available in History. |
| Archive | A retained capture of session results. |

---

## Keyboard and accessible operation

Source: https://openroom.app/docs/shortcuts/

Navigate the Library, editor, and presenter with the keyboard and choose a readable participant view.

### General navigation

Use **Tab** and **Shift+Tab** to move between controls. Use **Enter** to activate a focused button or link and **Space** to toggle a focused checkbox or option. Standard menu and tab controls support their arrow-key navigation. Press **Escape** to dismiss a dialog or menu where a dismissal action is available.

Shortcuts involving letters or arrows are suspended while typing in text fields. Move focus out of the field before using presentation shortcuts.

### Library

| Key | Action |
| --- | --- |
| Space on a focused item | Select the item and show its details. |
| Enter on a focused item | Open the item. |
| Shift+F10 | Open the focused row's context menu. |
| Enter while renaming | Commit the name. |
| Escape while renaming | Cancel the edit. |

Moving focus away from an edited item title also commits its name. Use the details panel's **Move** picker as the keyboard-accessible alternative to dragging a deck into a folder.

### Deck editor

Use **Up** and **Down** within the slide rail to navigate thumbnails. Use the slide context menu or ribbon to duplicate, delete, and insert slides. Select a slide part to reach its corresponding property fields.

For canvas objects, **Delete** or **Backspace** removes the selected removable object when text editing is inactive. When typing, those keys retain their ordinary text-editing behavior.

Use **Review overflow** to locate content that exceeds its available area. Supply useful alt text for images and accessible titles for embedded web pages and PDFs.

### Presenter

| Key | Presenter before participation | Live host console |
| --- | --- | --- |
| Right arrow | Next reveal or slide | Next |
| Left arrow | Previous reveal or slide | Previous |
| Space | Next reveal or slide | The currently available primary action |
| Escape | Close the presenter | Dismiss the active overlay where applicable |
| H | — | Show or hide the current result |
| F | — | Freeze or unfreeze participation |

Live shortcuts require presenter authority. A presenter opened inside the deck editor uses its own navigation handling. Check the visible action label before pressing Space: it follows the current question state.

### Desktop file commands

| Command | macOS | Windows/Linux |
| --- | --- | --- |
| New file | Command+N | Ctrl+N |
| Open file | Command+O | Ctrl+O |

Use the editor's **File → Save** and **Save as…** buttons to save local decks. Use the installed application's File menu to confirm available keyboard commands on that platform.

### Participant reading and input

Choose **Reading** for a document-style view of slide content. Choose **Slide** when the exact slide composition or freehand annotations matter. Use the provided move controls for ranking questions and the labelled inputs for gaps and matching.

Interface language controls offer English, French, and German where available. They change interface labels; authored lesson text keeps its original language.

For listening tasks, use the transcript after the host releases it. For voice homework, review the playback before saving and use **Download** to preserve a local copy when a retry is necessary.

### Read and print this manual

Use **Search the manual** for control names or tasks. On a small screen, expand **Browse topics** to navigate chapters. Each chapter has an **On this page** list and related instructions.

Use the browser's Print command for a chapter; navigation is omitted from the printed layout. The [complete text edition](https://openroom.app/llms-full.txt) contains the same chapter source in one downloadable file.

---

## Troubleshooting

Source: https://openroom.app/docs/troubleshooting/

Recover saves, participation, media, learner work, and integration connections.

### A deck has unsaved changes

Keep the editor open and restore the connection. Wait for the save status. If the automatic retries have finished, make a further edit to retry. Preserve important text locally before closing a page that still reports a save error.

For a version conflict, review **Keep this draft** and **Use saved version**. Choose the intended content only after considering the other client's changes. In Desktop, save a separate local copy before resolving a cloud synchronization conflict.

### Start session is blocked

Read the readiness or validation message and open the named question or slide. Complete missing prompts, options, gap answers, or other required fields. Resolve any draft conflict and allow the save to finish, then retry.

For a permissions error, check the selected account, current space membership, and role. For a resource error, restore access to the referenced media and retry its upload or packaging.

### A slide is clipped or difficult to read

Use **Review overflow** in the editor. Shorten the affected wording, enlarge the text box, reduce formatting size, change the layout, or split the content across slides. Recheck after changing the aspect ratio or applying a brand kit.

Open the presenter and the participant's Reading view. Use reading documents for long passages and keep essential slide labels concise.

### A participant cannot join

Check the current eight-character code or invitation and the network connection. A session ended by the host or removed by retention requires a new live session.

For a named learner session, use the personal learner credential for that context and wait until the host starts. For a roster session, use its individual roster invitation. Ask the issuer to replace an expired or revoked link.

To restore a generated session name in another browser, use **Rejoin with handle** and enter the exact name shown previously. To retain the current browser's participation, return using the same browser and session address.

### An answer is not accepted

Check whether the question is open, the session is frozen, and an answer has already been submitted. Some questions permit changes; others retain the submitted answer. For a group question, the assigned spokesperson submits.

Complete all required parts of a ranking, gap, or matching answer. Follow the numeric bounds or text character limit shown. Wait for **Answer received** before moving away. After a connection failure, inspect the answered state before submitting again.

### The host or stage stops updating

Restore the network and check the host's connection label. **Polling** is a fallback connection with periodic updates. **Offline** requires recovery before relying on new commands.

Use **Live now** to resume the same session through the Library. If a stage link failed to load, use **Stage — retry**. Permit the new window when the browser blocks it. Open the stage on the intended projector or shared screen.

For co-facilitation, check the current presenter. Pass presentation to the correct person or use the available recovery action.

### Sound, pictures, or embedded pages fail

Test the resource in preview and check its address. Restore the relevant online service or replace the resource with an accessible one. A website can refuse embedding; use its open-page action or import supported text as reading material.

Start audio with an explicit playback action, unmute the computer, and choose the correct output device. Check whether the task uses Room audio or Individual listening. Test room sound again after presenter handoff.

For `.openroom` export, every packaged resource must be retrievable and within the file limits. Correct the failing resource and repeat **Save a copy**.

### A learner link or assignment is unavailable

Ask the teacher to check link expiry, revocation, and the selected learner. Replace a lost link by selecting the same learner identity.

For a missing task, check its audience in Notes and save the assignment. For an updated task, refresh the learner page. If a saved response refers to an earlier task revision, use the offered refresh/retry flow and preserve any unsent wording first.

### A recording cannot be saved

Allow microphone access on a secure page and keep the recording tab active. Stop within five minutes. Listen to the preview before saving.

If upload fails, retain the preview, download a local copy if needed, restore the connection, and use **Try again**. Check the 20 MiB limit and the ten-recording retention limit for that learner and task. Trashed recordings still count while retained.

### Feedback is missing or outdated

Confirm that the response belongs to the expected learner. **Save draft** keeps feedback with the reviewers; use **Share feedback** or the updated-feedback sharing action to publish it. Refresh the learner's Feedback tab after publication.

If another reviewer changed the work, refresh and review the latest version before saving your intended feedback again.

### Saved results are unavailable

Sign in with an account that can access the original space. Check whether the 90-day archive period has expired. Individual responses are downloadable only when they were captured in that archive.

For a recap, prepare it before the live response purge. Downloaded copies must be recovered from your own storage if the server copy has expired.

### An agent or PowerPoint connection fails

For a token-based agent, confirm the MCP origin, Authorization header, and token validity. For an account connection, repeat consent for the intended account. Check current space membership after reconnecting.

For a Desktop agent, check the installed harness, sign-in, provider key, and provider quota. Inspect edits already completed before retrying a turn.

For the local PowerPoint preview, keep the HTTPS server running and renew its development certificate when expired. Reconnect the task pane after a reload. Use **Show selected slide** if automatic activation is unavailable, and rehearse before the event.

### Report a reproducible problem

Record the page or task, the exact visible error, the account role, the steps that led to it, and whether a retry changed the result. Include a screenshot only after checking it for private content. Remove personal tokens, learner links, roster invitations, and host-control links before sharing diagnostic material.