[sw005320]

#57 never reached master. It was stacked on #55, and #55 merged into master
first — so when #57 merged two hours later it went into
notebooks/pin-released-espnet, a branch master had already taken and stopped
following. GitHub only retargets a stacked pull request when its base branch is
deleted. My mistake for stacking; this is the same work, aimed at master.

It is why sds_demo.ipynb and asr_streaming_demo.ipynb are not in
Demos/, and why the
front page has no badge.

What is in here

Every demo runs weekly. The workflow ran one course notebook, and its
pull_request paths did not mention Demos/ at all, so changing a demo ran
nothing. All nine notebooks are in the matrix, and what to install is asked of
each notebook — run_notebook.py --print-install reads its own pip lines, so a
demo that starts needing another extra says so in the cell a reader runs.

Two more demos, each run end to end before committing:

• asr_streaming_demo.ipynb — the old 2021 streaming notebook made to work, on
  espnet/tedlium2_streaming_transformer, the weights Keqi Deng trained, copied
  into the organization with credit so the link cannot rot.
• sds_demo.ipynb — spoken dialogue with the parts showing: OWSM-CTC hears,
  Qwen2.5-0.5B answers, VITS speaks. It replaces the one row in espnet's demo
  table that was a link to a recipe rather than a notebook.

Badges, and the checks that stop them being decoration. Each demo carries
the workflow's status beside its Colab badge. check_layout.py fails if a demo
has no badge, if it is not in the workflow matrix, if it is not listed in the
README, or if a README links to a notebook that is not there — which caught the
root README pointing at eight files that the flattening had moved.

Tests for the parsing CI trusts (from review): seventeen cases, three of
which were bugs — a trailing comment became four packages, a line-continued
command raised ValueError, and drop_installs left half of one behind as
invalid Python.

What green means is written down: every cell ran on a clean CPU runner last
Sunday; it does not mean the output was right; and a table of what a demo
depends on that lives outside this repository.

The front page now lists the nine demos, says unmaintained/ is unchecked,
and stops presenting four courses as though they were alike — one is maintained,
the other three have not been checked in years and are kept as a record.

🤖 Generated with Claude Code

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[sw005320]

Right — it is an interface, and it was only written down in the tests.

tools/README.md now states it, in two tables, under "What CI installs: the
install cell is the contract". Demos/README.md links there from the rule
about pinning a release, which is where an author is standing when they write
the cell.

Read as a dependency: !pip install and %pip install at the start of a
line; flags passed through as they are; quoting undone (the shell would
otherwise hand pip a name with quotation marks in it); # comments dropped; a
command continued over lines read as the one command it is; every install line,
in one cell or many.

Not read, each with its reason:

	why
git+https://…	deliberate. A demo pins a release — check_layout.py fails one that does not — so it does the same thing in April as today, and a break on master the night before someone opens it is not their problem. Installing espnet from git in CI would also test something other than what a reader gets, which would make a pass here mean nothing.
an indented install, inside an if	what it asks for depends on a choice made when the notebook runs. The course notebook installs S3PRL only for the WavLM front-ends; CI cannot know which branch a reader takes.
!apt-get, !cd repo && pip install .	removed before execution, because the runner is not Colab, but not treated as a Python dependency.
anything in a markdown cell	it is prose.

Two more things the section says. How to see what CI will install, which is to
ask rather than to read the regex:

$ python tools/run_notebook.py Demos/enh_demo.ipynb --print-install
-q espnet[enh]==202610.post1 espnet_model_zoo librosa

And what to do when a notebook needs something the contract cannot express: it
is a Courses/ document rather than a demo, because the weekly badge would be
promising something it cannot keep.

Every row of both tables is a case in tests/test_run_notebook.py, so the
documentation and the behaviour are checked against each other rather than
drifting.