TOEIC Speaking Simulator

A single-file web app that runs a TOEIC Speaking mock exam from a Markdown file — real exam timing, automatic countdown, cue tones, and microphone recording so you can play your answers back afterwards.

No install, no server, no account. It is one HTML file.

▶ Try it now (no download): https://sunggap.github.io/toeic-speaking-simulator/

지금 바로 사용 (다운로드 불필요): https://sunggap.github.io/toeic-speaking-simulator/ — https:// 주소라서 마이크 녹음·음성 재생이 정상 작동합니다.

The app itself is bilingual (English / 한국어) — use the EN / 한국어 toggle at the top-right. It auto-selects Korean for Korean-language browsers.

---

한국어 안내 (Korean quick guide)

이게 뭔가요? 마크다운(.md) 파일로 만든 문제를 실제 TOEIC 스피킹 시험처럼 시간 제한·자동 카운트다운·신호음과 함께 풀고, 답변을 자동 녹음해서 다시 들어보는 웹앱입니다. 설치·서버·계정 불필요, HTML 파일 하나입니다.

시작하기

1. index.html을 브라우저(Chrome/Edge/Firefox)로 엽니다. 녹음까지 쓰려면 https:// 주소(아래 GitHub로 게시) 또는 http://localhost에서 여세요. 파일 더블클릭(file://)은 타이머·음성재생은 되지만 브라우저에 따라 마이크가 막힙니다.
2. 시험 파일을 드롭하거나 파일 선택 / 마크다운 붙여넣기. 처음엔 samples/practice_test_1.md로 시험해 보세요.
3. 녹음까지 하려면 마이크 점검 후 시작 — 장치 선택 + 입력 레벨 확인 + 4초 테스트 녹음/재생 후 시작. 타이머만 필요하면 시험 시작(마이크 권한을 묻지 않음).
4. 각 문제: 지시문(Directions) → 준비 시간 카운트다운 → 신호음 → 응답 시간 카운트다운(녹음) → 자동으로 다음. 듣기 문제(Q5–10)는 음성으로 재생되고 대본 보기 버튼으로 확인. 지시문(Directions)은 실제 시험처럼 영어로 표시되며 (공식 문구를 그대로 쓰지 않은 짧은 자체 안내문), 화면의 버튼·라벨만 EN/한국어 토글을 따릅니다.
5. 시험 종료 화면에서 답변을 재생·다운로드. 시험 중 아무 때나 Space를 누르면 다음 단계로 넘어갑니다.

시험 파일은 어디서? 직접 준비합니다. 가장 쉬운 방법: AI-TEST-KIT.md 파일 하나를 ChatGPT/Claude/Gemini에 붙여넣고 "이 kit에 따라 새 TOEIC 스피킹 연습 시험 만들어줘" 또는 "11번 의견 문제만 5개 만들어줘" 라고 요청 → 결과를 my_test.md로 저장해 불러옵니다. 형식 상세는 GUIDELINE.md.

커스텀 연습 개요 화면에서 문항별 포함/제외, 유형 일괄 선택("질문에 답하기" 등), 선택 세트 1–20회 반복이 가능합니다. 파일에 특정 유형만 있거나 개수가 표준보다 많아도 그대로 실행되며, 개요에 "앞으로 진행될 내용"이 요약 표시됩니다.

파일이 잘못됐을 때 ## Question 헤더가 하나도 없는 등 심각한 오류면 앱 안의 편집기로 전환되어 오류 메시지와 함께 바로 고칠 수 있습니다. 사소한 문제(알 수 없는 type, 제목 없음 등)는 경고만 표시하고 시험은 그대로 진행됩니다.

GitHub로 게시 정적 파일이라 GitHub Pages로 바로 호스팅됩니다. 아래 Publish with GitHub 참고 — https:// 주소라서 마이크·음성재생이 정상 작동합니다.

제약 녹음은 자동 저장되지 않으니 종료 화면에서 다운로드하세요(.webm). 채점·발음 평가 기능은 없습니다(시간 관리 + 자기 검토 도구). Safari는 녹음 지원이 제한적입니다.

---

Quick start

1. Open index.html in a modern browser (Chrome, Edge, or Firefox). For recording to work the page must be in a secure context — a hosted https:// URL (see Publish with GitHub below) or http://localhost. Double-clicking the file (file://) runs the timer but some browsers block the microphone.
2. Drop a test file onto the page, or click Choose file / Paste Markdown. Try samples/practice_test_1.md first. (No test file? See Where do test files come from? below — paste AI-TEST-KIT.md into an AI.) On the overview you can pick which questions to include and repeat a selection.
3. To record your answers, click Check mic & start — pick your input device, watch the level meter, and record a 4-second test clip. Or click Start test to run timer-only (it never asks for microphone permission).
4. For each question: directions → Preparation countdown → a beep → Response countdown (recording if the mic was set up) → it moves on automatically. Listening questions (Q5–10) are spoken aloud; press Show script to see the wording.
5. On the Test complete screen, play each response back and download the audio.

Press Space at any time to jump to the next phase.

---

Where do test files come from?

You bring your own. A test file is plain Markdown — see GUIDELINE.md for the full format.

The easy way: paste the single file AI-TEST-KIT.md into ChatGPT / Claude / Gemini and ask for a test — e.g. "Make me a new full TOEIC Speaking practice test following this kit", or "Make 5 Question-11 opinion prompts only". That file contains the format spec, the task list, and a worked example, so the AI can produce a ready-to-load .md from that one paste. Save the output as my_test.md and open it in the simulator.

The app ships with one sample and is otherwise empty by design — you practice with fresh AI-generated material every time.

Custom sessions

On the overview screen you can:

• Include / exclude individual questions with the checkboxes.
• Quick-select a whole task type ("Respond to questions", "Express an opinion", …).
• Repeat the selected set 1–20 times — e.g. tick only Question 11 and repeat 10× to drill opinion answers.

If the file has a problem

• Broken file (no ## Question headers, unreadable): the app opens an editor with the error message and your text, so you fix it and press Re-parse — no need to leave the app.
• Minor issues (unknown type, missing title, empty question): the app loads the test anyway and shows a yellow warnings panel listing each one. Use Edit source on the overview to correct them.

---

Features

• Automatic timing per official task type (Read aloud 45/45, Describe a picture 45/30, Respond to questions 3/15, Respond with info 45/15, Express an opinion 45/60) — all overridable in the file.
• Question sets (Q5–7, Q8–10): one scenario, multiple timed prompts.
• Listening prompts — Q5–10 questions are played with text-to-speech and the script is hidden behind a Show script button, like the real test. The prep timer waits for the voice to finish. Configurable per question (speak, hide_text).
• Microphone check before the test — live input meter + record-and-play-back a test clip.
• Cue tones at each phase change, like the real test.
• Recording & playback via the browser (MediaRecorder). Each response is a separate audio clip you can replay or download (.webm).
• Practice mode — pause, skip, and re-read directions without time pressure.
• Custom sessions — include only chosen questions or a whole task type, and repeat the set up to 20× for focused drilling.
• Forgiving input — a broken file opens an in-app editor with the error; minor problems load anyway with a warnings panel.
• Bilingual UI (EN / 한국어) — every screen and control. Toggle top-right; remembers your choice. The exam directions stay in English, matching the real test's structure with short original wording (not copied from any test).
• "Describe a picture" without a picture — the file gives a short written scene description that you describe aloud (an image URL still works if you want one).
• Works fully offline. Nothing is uploaded; recordings stay in the browser tab until you download them or close it.

---

Exam structure it models

Questions	Task	Prep	Response
1–2	Read a text aloud	45s	45s
3–4	Describe a picture	45s	30s
5–7	Respond to questions	3s	15/15/30s
8–10	Respond to questions using information	45s	15/15/30s
11	Express an opinion	45s	60s

Your file decides which of these appear and in what order.

---

Notes & limitations

• Recordings are not saved automatically. Download them from the results screen before closing the tab. Format is .webm (Chrome/Edge/Firefox) — playable in VLC, or convert with any tool.
• Images are optional. "Describe a picture" questions normally use a written scene description. If you do add an - image: URL, use a full https:// URL or a data: URI; relative paths (images/pic.jpg) only work when the folder is served over http://.
• Safari's MediaRecorder support is limited; Chrome, Edge or Firefox recommended.
• Text-to-speech uses whatever English voice the browser/OS provides; quality varies. No scoring or speech evaluation — this is a timing and self-review tool.

---

Publish with GitHub

Because the app is one static file, GitHub can host and distribute it directly.

Option A — GitHub Pages (recommended: gives a live URL, mic works)

From this folder (already a git repo — git init done):

git add -A
git commit -m "TOEIC Speaking Simulator"
gh repo create toeic-speaking-simulator --public --source=. --push
gh api -X POST repos/{owner}/toeic-speaking-simulator/pages -f "source[branch]=main" -f "source[path]=/"

Or without the gh CLI: create the repo on github.com, git remote add origin <url>, git push -u origin main, then Settings → Pages → Source: Deploy from a branch → main / / (root) → Save.

After ~1 minute the app is live at https://<user>.github.io/toeic-speaking-simulator/. It's an https:// URL, so microphone recording and text-to-speech work. Share the link — users just open it, nothing to download.

Every later git push to main redeploys the site automatically.

Option B — GitHub Release (versioned download)

Attach the app as a downloadable asset on a tagged version:

# one-time: package the app + docs + sample
zip -r toeic-speaking-simulator.zip index.html GUIDELINE.md AI-TEST-KIT.md README.md LICENSE samples

gh release create v1.0.0 \
  index.html toeic-speaking-simulator.zip \
  --title "TOEIC Speaking Simulator v1.0.0" \
  --notes "Single-file mock-exam runner. Download index.html and open it, or unzip the bundle."

Users download index.html from the release's Assets and open it locally (file:// — timer + TTS work; some browsers block the mic, so prefer Option A for recording). The .zip gives them the guideline, prompt and sample too.

You can also just tell people to use the green Code → Download ZIP button on the repo — no release needed.

---

Getting it found in search

The page ships with SEO basics: a descriptive <title> and <meta name="description">, Open Graph tags for link previews, SoftwareApplication JSON-LD, a canonical URL, and static intro + FAQ text and a <noscript> block so crawlers see real content before the app's JavaScript runs. robots.txt and sitemap.xml are in the repo root.

To actually get indexed and track performance you must do this yourself (it needs your Google account):

1. Google Search Console → add property https://sunggap.github.io/toeic-speaking-simulator/, verify (the "HTML tag" method — paste the <meta> it gives you into <head>).
2. Submit the sitemap: https://sunggap.github.io/toeic-speaking-simulator/sitemap.xml.
3. Use URL Inspection → Request indexing for the homepage.
4. Optionally repeat in Bing Webmaster Tools.

Ranking then comes from links and use, not tags — see the project's launch plan (share on dev / language-learning communities, add to "awesome" lists, write a build post that links back). Big keywords like "TOEIC speaking" are dominated by commercial sites; aim for long-tail ("free TOEIC speaking simulator", "토익 스피킹 모의고사 무료").

---

Files

File	Purpose
index.html	The app. Open this.
AI-TEST-KIT.md	Paste into an AI to generate new tests (spec + example).
GUIDELINE.md	Full Markdown test-file format specification.
samples/practice_test_1.md	Example test (7 question blocks, all task types).
LICENSE	MIT license.
robots.txt, sitemap.xml	Search-engine crawl hints for the hosted site.

---

Existing similar projects

No existing project matched this one: a Markdown-driven TOEIC Speaking mock exam that runs entirely in the browser with exam timing and audio recording + playback.

rohitpanicker06/TOEFL-Mastery-...Speech-Recognition is the nearest speaking-test project, but it works very differently:

• Stack: MERN — React/MUI frontend + Node/Express + MongoDB + Auth0. Needs a running server and database; questions are DB documents created through an admin UI, not files.
• "Speech recognition": the SpeechToText.jsx component uses react-speech-recognition (the browser Web Speech API) to transcribe speech to text into a textarea — it does not record or play back audio.
• "AI assessment": the Grammarly Editor SDK runs on that transcript and returns writing statistics. There is no pronunciation/fluency analysis of the voice, and no exam countdown on the speaking section.

So it does not overlap in workflow (Markdown in), delivery (single file, offline), or the "record your voice and listen back" feature. TOEIC LC/RC simulators like Youssef0356/TOEIC-Exam-Simulator are unrelated (no speaking section).

---

License / 라이선스

MIT License — see LICENSE. Copyright © 2026 SunggaP. Use, copy, modify and redistribute freely; keep the copyright notice.

MIT 라이선스입니다. 자유롭게 사용·수정·재배포할 수 있으며, 저작권 고지만 유지하면 됩니다.

Credits / 제작

Designed and built with Claude Code (Anthropic) — the app code, the Markdown format, the docs and this README were generated in a Claude Code session.

이 프로젝트(앱 코드, 마크다운 형식, 문서, README)는 Claude Code(Anthropic)로 제작되었습니다.

TOEIC and TOEIC Speaking are trademarks of ETS. This is an independent study tool, not affiliated with or endorsed by ETS. / TOEIC은 ETS의 상표이며, 본 도구는 ETS와 무관한 비공식 학습 도구입니다.

---

Disclaimer / 책임과 한계

English. This software is provided "as is", without warranty of any kind (see LICENSE). It is an unofficial self-study aid, not an official TOEIC test and not a substitute for one. The question types, timing and on-screen wording approximate the publicly documented TOEIC Speaking format and may differ from the current official test — always confirm details with official ETS materials. The app does not score answers or evaluate pronunciation or fluency. You are responsible for the content of any test files you load or generate with an AI, and for checking that AI-generated questions are accurate and appropriate. Recordings and settings stay in your own browser; nothing is uploaded, and the authors are not responsible for any loss of recordings or data. Use of any third-party service you paste content into (ChatGPT, Claude, Gemini, GitHub, etc.) is subject to that service's own terms.

한국어. 본 소프트웨어는 어떠한 종류의 보증도 없이 "있는 그대로" 제공됩니다 (LICENSE 참조). 비공식 자기 학습 보조 도구이며, 공식 TOEIC 시험이 아니고 이를 대체하지 않습니다. 문제 유형·시간·화면 문구는 공개된 TOEIC 스피킹 형식을 근사한 것으로, 현행 공식 시험과 다를 수 있으므로 세부 사항은 반드시 ETS 공식 자료로 확인하세요. 이 앱은 답변을 채점하거나 발음·유창성을 평가하지 않습니다. 직접 불러오거나 AI로 생성한 시험 파일의 내용, 그리고 AI가 생성한 문제의 정확성과 적절성 확인은 사용자 책임입니다. 녹음과 설정은 사용자 브라우저에만 저장되며 어디에도 업로드되지 않습니다. 제작자는 녹음·데이터 손실에 대해 책임지지 않습니다. 내용을 붙여넣는 외부 서비스(ChatGPT, Claude, Gemini, GitHub 등)의 이용은 해당 서비스의 약관을 따릅니다.