Guide

How it works

Traced Dialogic Assessment Tool brings together three things: the recording of an oral exam, its transcript, and the course material the exam is about. The app takes the key ideas from the course material, finds where they come up in what was said, and lays the conversation out so you can see who said what, when, and how well.

The window has two views. Switch between them with the switch at the top right, or ⌘1 and ⌘2 (Ctrl+1 and Ctrl+2 on Windows and Linux).

A typical exam goes like this:

1. Add an API key for OpenAI or Anthropic (once).
2. Import the transcript and load the recording.
3. Add the course material and generate its key ideas.
4. Find the key ideas in the transcript, with or without AI.
5. Work through the exam in the Traced view, and save the project.

Getting started

Download the app from the Download page and install it like any other. It needs no account. A short tour shows you around the first time; take it again from Help ▸ Welcome Tour.

Two things are worth having to hand:

• An OpenAI or Anthropic API key for the AI tasks: key ideas, AI and hybrid matches, interactional themes, question detection and keyword summaries. Everything else works without one. See Setting up AI.
• ffmpeg, to draw the recording's waveform and read formats the player can't. The app offers to download it the first time it's needed. See Recording and waveform.

Setting up AI

In the Editor's AI Configuration panel, paste a key into the OpenAI or Anthropic field and press Save. The app checks the key with the provider before keeping it. Get a key opens the provider's page for making one. You can add both.

• Keys are encrypted by your operating system's keychain and stay on your computer. The × beside a saved key removes it.
• Model for every task: Automatic uses a fast, inexpensive current model from a provider you have a key for. Pick another to use it for every task.
• Advanced Settings… sets a model for each task separately, along with the settings that model takes (reasoning effort, thinking, temperature, output limit), each task's prompt, and the score a hybrid match needs. Prompts you edit keep your edits; the others follow the app's defaults as they improve.
• Offer models not in the app's list shows every model your key can use. Enter the price of one that isn't in the list yourself, so its costs can be counted.
• What you've spent is shown at the bottom of the panel: this session, this month and all time. Each AI task also reports its cost when it finishes.

Projects

Each exam is a project: one .dialogic file holding the transcript and your edits to it, the recording's location, the course material, the key ideas, every analysis and AI result, your highlights, questions and slide marks. AI results are saved with it, so nothing is paid for twice.

• File ▸ New, Open…, Open Recent, Save and Save As… work as you'd expect. The project's name is in the title bar.
• Drop files anywhere on the window: a project to open it, a transcript to import it, a recording to load it, or a transcript and recording together.
• Undo (⌘Z, Ctrl+Z) covers every change, including transcript edits and AI results. An AI run is one step.
• The recording and slides are stored both by full path and relative to the project, so a folder holding the project and its recording can be moved or shared as a whole.

Transcript and recording

Importing a transcript

File ▸ Import Transcript…, or drop the file on the window. You can also type or paste a transcript straight into the Transcript Editor. The format is recognised from the file's contents:

A file that labels its speakers (S_01, SPEAKER_00) lists them first, so you can name them before the import. Speakers are written at the start of each line, as in Examiner:; that is how Participants, Speaking Turns and Questions know who is talking. Jefferson and Mondada notation is kept exactly as typed.

Importing over a transcript that has matches, highlights or questions on it lists what would be lost first. Undo brings it all back.

The Transcript Editor

Correct the transcript as you would in any text editor; your edits are saved, and matches, highlights, questions, word timings and sync codes stay on the right words.

• Sync codes tie lines to moments in the recording, shown as clocks in the margin. Click a clock to play from that line, drag it to move it, or click an empty margin to sync that line to the playhead. Right-click for Sync Line to Playhead, Remove Sync Code and Play from This Line.
• Follow scrolls the editor with the recording.
• The chips above the text show or hide each kind of match: keyword, AI, hybrid and CA findings.
• Playback keys type as normal while you're writing; ⌘⇧Space (Ctrl+Shift+Space) plays and pauses even then.

Recording and waveform

Drop a recording on the window, or choose one in the Audio Waveform panel. MP3, MP4, WAV, OGG, WebM, M4A, AAC and FLAC play directly; MPG, WMV, WMA, FLV, 3GP, MXF and DV are read too. If the player can't play a file, the app says which codec it uses and whether the sound still plays, and still draws its waveform.

The waveform is drawn by ffmpeg. The first time it's needed, the app offers to Download it, to Use a copy I have…, or Not now; you can set it up later in Preferences ▸ Media. Copies already installed, for example with Homebrew, are found by themselves. The download comes from well-known third-party builds, checked against their checksums where they publish them.

• Zoom with the mouse wheel, a trackpad pinch, the toolbar or = and −; 0 shows the whole recording. Swipe sideways or Shift-scroll to pan.
• Click to go to a moment; drag along the ruler to scrub. The follow menu keeps the playhead in view, by page or smoothly.
• Markers show questions (flags), highlights (bands) and low-confidence words (ticks).
• Play at up to 8× speed. The speaker button sets the volume, which is saved with the project.

Course material and key ideas

Key ideas are the concepts a student could be asked to explain. Everything the app finds in a transcript starts from them.

1. In Corpus Input, paste or type the course readings or notes, or use Add Files… (or a drop) for text, Markdown and PDF files.
2. Press Generate Key Ideas. The model picks out the key concepts and writes a study summary.

Key Ideas lists each concept with its importance (one to five dots), a definition and explanation, and its aliases: other names, the broader term, the English term for material in another language. Also as lists the plural and other forms it is found by. Remove one with its ×. Export… saves the list, and Load… reads a saved one, to use the same key ideas for several exams.

The Generated Study Summary explains the main concepts and how they connect. Edit it, Copy it or Save… it as a file.

Analysing the transcript

Analyze Transcript offers four ways to find where the key ideas, and features of the conversation, occur. Each keeps its own results, which are marked in the Transcript Editor in their own colour and listed in Matches, with the reason for each.

• AI looks for up to limits how many matches the AI method returns.
• Each method's ⋯ menu saves its results to a file, loads saved ones, or clears them. Clear All clears every method; Undo brings them back.
• Comments and reasons come back in the transcript's language, even when the course material is in another. Matching understands English plurals and possessives, and Danish definite and plural forms.

The Traced view

The Traced view is for reading the exam closely. Its panels work together: click a line, a turn, a keyword or a question, and the transcript and recording go there. The transport bar at the bottom plays, scrubs and sets the volume. Panels not shown are in the Panels menu.

Transcript

The conversation by speaker. The concepts the analyses found are underlined, taken from the best set you have run (hybrid, then AI, then keyword matches); turn Highlight concepts off to read without them. Click a line to play from it. Select some text to highlight it in one of four colours, or to mark it as a question.

Participants and Speaking Turns

Participants shows each speaker's share of the speaking time, turns, words and questions asked, and, for transcripts with word confidence, how sure the recogniser was of their words. Select a speaker to dim the others in the transcript.

Speaking Turns draws each turn at its real length on a timeline, one lane per speaker, as Bars or as Bubbles sized by how much was said. Zoom and pan as on the waveform, click a turn to play from it, and use the link button to keep it in step with the Audio Waveform.

Keywords

The key ideas as a cloud, sized by importance, with how many lines each is on. Click a keyword to go to its first line, and again for the next; Shift-click to show several at once. Summarize Usage asks the model how the keyword is used across the exam, or by the speaker selected in Participants. Summaries are saved with the project.

Highlights

Every passage you've highlighted, in order. Write a note on each, tag it with the keywords it shows (+ keyword), change its colour or remove it. Click one to go to it.

Questions

Who asks, who answers, and how long the pauses are. Questions are found by rule (a question mark, or the shape of a question), by an AI pass, or both: choose under Detection. Add one yourself by selecting it in the transcript and choosing Question; set a wrong one aside with its ×.

CA Analysis

The conversation-analysis findings: notation found by rule, and themes found by the model, marked AI. Group them by kind, by family or in transcript order, and choose which kinds to show. Click a finding to go to it. The notation rules can be run from here too; the AI themes are run from the Editor's Analyze Transcript.

Slides, Video, Audio Waveform and Project

• Slides: load the lecture's slides (a PDF, or one image per slide) with Load Slides… or a drop. Prev, Next and the slide picker only browse; Mark Slide Here records that the slide shown comes up at the playhead. During playback the panel follows the marks.
• Video shows the recording's picture, when it has one.
• Audio Waveform works as in the Editor, with its own zoom.
• Project summarises what the open project holds.

Word confidence

Transcripts from Dote-Whisper and the Whisper family say how sure the recogniser was of each word. Both transcript views can show it, from the confidence menu above the text:

• Heat underline: red and amber under the least certain words (the bands are set in Preferences ▸ Transcript).
• Tint low-confidence words below the threshold.
• Threshold filter: dims the words below it, to proofread the rest.

The threshold (80% to begin with) is a slider, saved with each project, since recordings differ. While a display is on, low-confidence words are ticked on the timelines. A word you've corrected no longer counts as low-confidence.

Arranging the window

Each view is a board of panels. Drag a panel's title bar to move it, or onto another panel to swap the two; drag its corner to resize it. Close a panel with its × and bring it back from the Panels menu, which counts the closed ones. (The Editor's transcript and waveform stay put.)

Panels ▸ Save current layout… keeps an arrangement under a name; saved layouts are listed in the same menu for every project, and the trash icon deletes one. Reset layout, or View ▸ Reset Panel Layout, goes back to the default. In the shortcuts list (?), any panel can be given a key that shows or hides it.

Keyboard shortcuts

Use Ctrl for ⌘ on Windows and Linux. Press ? for the full list; click a shortcut there and press new keys to change it.

Preferences

Open with ⌘, (File ▸ Preferences… on Windows and Linux). Changes are saved as you make them.

Costs and privacy

The app is free. AI tasks are paid for by you, to the provider, through your own key, at the provider's prices. They are small: running every AI task on the demo exam (27 lines, 600 words of course notes) with the default Claude model cost less than one US cent. Longer exams and material, and larger models, cost more.

Everything else stays on your computer. The full details are in Privacy & Terms.

Updates

When a new version is out, the app shows what's new and how to get it. On a Mac, and with the Windows installer, it can also download the update in the background and install it the next time you quit — choose in Preferences ▸ Updates.

Feedback and problems

Help ▸ Send Feedback… (also in the status bar) goes straight to the developers. You see exactly what is sent before you send it: your words, your app version and operating system, and, only if you tick it, the end of the app's log. Your projects are never included.

If something goes wrong, the app offers to send the details for you. You can also use the Feedback page.

Moving from version 1

Version 2 installs beside "Dialogic Assessment Tool (Ver 0.1)" and opens its .dialogic.json projects, saving them as .dialogic next to the original, which is left untouched. Before you switch:

1. Open each version 1 project and save it once more in version 1. Version 1 copied Traced-view highlights, questions and slide marks into the project only when it saved.
2. Copy any AI prompts you changed into a text file; settings don't carry over.
3. Have your API key to hand: you enter it again.

Check timings in version 1 projects whose transcript you edited: version 1 moved sync codes as you typed but threw the text away. The changelog has the full release notes.

Troubleshooting

An AI task failed. The message says why. When the key is missing or rejected, it has a button to AI Configuration. A setting a model refuses is remembered and skipped from then on (Advanced Settings lists them).

The recording won't play. The app names the file's codec. Convert it to MP4 (H.264 and AAC) or MP3 and load the copy; the waveform and timings still match.

No waveform. ffmpeg isn't set up: use the button in the Audio Waveform panel, or Preferences ▸ Media.

Participants, Speaking Turns or Questions are empty. Lines need to start with the speaker's name, as in Examiner:. Without sync codes, turns are laid out by line rather than time.

The app won't open on macOS. Make sure it's in Applications, then open it again.

Something looks wrong. Help ▸ Show Logs… shows what the app has been doing; include it in a report with "Include recent activity".

Start fresh. Preferences ▸ Advanced ▸ Settings folder opens the folder holding your preferences. Quit the app and remove it to reset everything, API keys included. Your projects are elsewhere and are not affected.