{"id":46481207,"url":"https://github.com/itsupera/onsei","last_synced_at":"2026-03-06T08:15:47.197Z","repository":{"id":37855742,"uuid":"368814929","full_name":"itsupera/onsei","owner":"itsupera","description":"Japanese pitch accent practice tool","archived":false,"fork":false,"pushed_at":"2022-06-15T15:24:57.000Z","size":15560,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-03-05T23:08:14.015Z","etag":null,"topics":["japanese-study","pitch-accent","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsupera.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-19T09:31:20.000Z","updated_at":"2023-02-16T21:29:21.000Z","dependencies_parsed_at":"2022-08-19T09:12:51.195Z","dependency_job_id":null,"html_url":"https://github.com/itsupera/onsei","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/itsupera/onsei","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsupera%2Fonsei","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsupera%2Fonsei/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsupera%2Fonsei/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsupera%2Fonsei/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsupera","download_url":"https://codeload.github.com/itsupera/onsei/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsupera%2Fonsei/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30167195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T07:56:45.623Z","status":"ssl_error","status_checked_at":"2026-03-06T07:55:55.621Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["japanese-study","pitch-accent","python"],"created_at":"2026-03-06T08:15:46.544Z","updated_at":"2026-03-06T08:15:47.179Z","avatar_url":"https://github.com/itsupera.png","language":"Python","funding_links":["https://www.buymeacoffee.com/itsupera"],"categories":[],"sub_categories":[],"readme":"\nOnsei: Japanese pitch accent practice tool\n===========================================\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/itsupera/onsei/HEAD?urlpath=voila/render/work/notebook.ipynb)\n[![Gitter](https://badges.gitter.im/itsupera-onsei/community.svg)](https://gitter.im/itsupera-onsei/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\u003cspan class=\"badge-buymeacoffee\"\u003e\n\u003ca href=\"https://www.buymeacoffee.com/itsupera\" title=\"Donate to this project using Buy Me A Coffee\"\u003e\u003cimg src=\"https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg\" alt=\"Buy Me A Coffee donate button\" /\u003e\u003c/a\u003e\n\u003c/span\u003e\n\nThis project aims at creating tools to automatically assess the pitch accent accuracy\nof a Japanese language learner, and help them practice their pitch-accent at the sentence level.\n\n- **PLEASE NOTE THAT THIS IS AN EXPERIMENTAL WORK IN PROGRESS !**\n\n- **Feedbacks and suggestions are welcome =\u003e [Gitter chat](https://gitter.im/itsupera-onsei/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge) or Github issues**\n\nHow to play with it\n--------------------\n\n[Click here](https://mybinder.org/v2/gh/itsupera/onsei/HEAD?urlpath=voila/render/work/notebook.ipynb)\nto deploy the web interface.\n\nNote that this can take a few minutes to load !\n\nDid you like it ? Please consider [donating](https://www.buymeacoffee.com/itsupera) to help me support future developments, thank you !\n\nWhat is it for ?\n-----------------\n\nAs Japanese is a pitch-accent based language, foreign learners that don't have a\npitch-accent or tonal mother tongue will likely struggle to identify and reproduce\nthe correct pitch patterns.\n\nIf you are completely novice to pitch-accent, I suggest you first start with an\nintroductory course such as [this one](https://www.kanshudo.com/howto/pitch).\n\nPracticing with sentence rather than individual words is interesting\nbecause there is a difference between the theoretical accent patterns in a sentence\nand how native speakers actually say it, for many reasons\n(emphasis on certain words, emotions, slurred speech...)\n\nSetup\n------\n\nThe following instructions have been tested on Ubuntu 20.20.\n\nSince there are many dependencies to compile from source, the easiest way is\nto build using Docker:\n\n```bash\ndocker build -t onsei .\n```\n\nThen run the following command:\n```\ndocker run -p 8866:8866 -v \"$PWD\":/home/jovyan/work --entrypoint=voila onsei:latest\n````\nOpen the interface in your web browser: http://localhost:8866/voila/render/work/notebook.ipynb\n\n\nFor development purpose, run the JupyterLab:\n```bash\ndocker run -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v \"$PWD\":/home/jovyan/work onsei:latest\n```\nOpen the notebook in your browser: http://127.0.0.1:8888/lab/tree/notebook.ipynb\n\nAlternatively, it should build with `jupyter-repo2docker`\n```bash\npip3 install jupyter-repo2docker\njupyter-repo2docker -E .\n```\n\nAPI\n----\n\nAn API version has been developed to create an [Anki addon](https://github.com/itsupera/onsei-anki) !\n\nTo setup it up:\n```bash\n# First build onsei base image\ndocker build -t onsei .\n# Then build the onsei-api image on top of it\ndocker build -f Dockerfile.api -t onsei-api .\ndocker run --network=host onsei-api\n# Open http://127.0.0.1:8000/ in your web browser\n```\n\nOr if you already have everything installed locally, can simply run it with:\n```bash\nuvicorn onsei.api:app\n```\n\nUsing the CLI\n--------------\n\nNote: you probably want to use the Jupyter notebook first, see instructions above.\n\nFor more advanced usages, a CLI is available.\n\n### Visualize a recording\n\n```bash\npython3 -m onsei.cli view \\\n    \"data/ps/ps1_boku_no_chijin-teacher2.wav\" \\\n    --sentence \"僕の知人の経営者に\"\n```\n\n### Comparing teacher and student recordings\n\nThe following script compares teacher and student recordings of the same sentence,\nshow a bunch of graphs to visualize the differences and computes a distance, i.e.,\nhow close the student pronunciation is to the teacher's.\n\nHere is an example with the sentence 僕の知人の経営者に (boku no chijin no keieisha ni).\nThe sample recordings are:\n- `data/ps/ps1_boku_no_chijin-student1.wav`: student mispronouncing words\n- `data/ps/ps1_boku_no_chijin-teacher2.wav`: teacher repeating with correct pronunciation\n- `data/ps/ps1_boku_no_chijin-student3.wav`: student trying again and fixing the mistakes\n\nFirst comparing the mispronounced sentence with the teacher's:\n```bash\npython3 -m onsei.cli compare \\\n    data/ps/ps1_boku_no_chijin-teacher2.wav \\\n    data/ps/ps1_boku_no_chijin-student1.wav \\\n    --sentence \"僕の知人の経営者に\"\n# Mean distance: 1.21 (smaller means student speech is closer to teacher)\n```\n![Graphs for the \"bad\" student](graphs_bad_student.png)\n\nThen comparing the rectified sentence with the teacher's:\n```bash\npython3 -m onsei.cli compare \\\n    data/ps/ps1_boku_no_chijin-teacher2.wav \\\n    data/ps/ps1_boku_no_chijin-student3.wav \\\n    --sentence \"僕の知人の経営者に\"\n# Mean distance: 0.57 (smaller means student speech is closer to teacher)\n```\n![Graphs for the \"good\" student](graphs_good_student.png)\n(Note that the natural offset in the pitch is removed when we normalize the pitches to compute the distance)\n\nAs the student fixes the mistakes, we can see that the computed distance lowers.\n\n### Other commands\n\nTo see other possible commands, see the help of the CLI:\n```bash\n# List of the commands\npython3 -m onsei.cli --help\n\n# Details on a specific command\npython3 -m onsei.cli \u003ccommand\u003e --help\n```\n\n\nMethodology\n------------\n\nIf you are interested in the way the comparison process works, here is an overview:\n\n- Crop both recordings to remove the noise before and after the sentence\n- Segment both recordings to find where each phoneme starts and ends\n- Align the student recording with the teacher's, using [Dynamic Time Warping (DTW)](https://en.wikipedia.org/wiki/Dynamic_time_warping) based on detected phonemes (by default) or on speech intensity\n- Apply the same alignment on the pitch signals and normalize them\n- Compute a mean distance based on the aligned and normalized pitch signals","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsupera%2Fonsei","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsupera%2Fonsei","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsupera%2Fonsei/lists"}