bdmvkit 0.2.0__tar.gz → 0.4.0__tar.gz

{bdmvkit-0.2.0/bdmvkit.egg-info → bdmvkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdmvkit
-Version: 0.2.0
+Version: 0.4.0
 Summary: Blu-ray (BDMV) authoring in pure Python: playlists, clip information, HDMV navigation, PGS subtitles
 Author: kajisho5
 License-Expression: LGPL-3.0-or-later
@@ -35,11 +35,14 @@ only to encode.
 
 日本語の説明は [README.ja.md](README.ja.md) にあります。
 
-**Status: 0.2.** Titles with chapters, sound and subtitle tracks, and menus
-whose buttons start titles, chapters and other menus. Pop-up menus (over a
-playing title) and menus with motion or music come next; they already work
-in [oncemore](https://github.com/kajisho5/oncemore), where this code comes
-from.
+**Status: 0.4.** Titles with chapters, sound and subtitle tracks;
+playlists (in order, at random or shuffled) and play all; menus whose
+buttons start titles, chapters, playlists and other menus, switch sound and
+subtitle tracks, or open a menu on a chosen button; loop counts, end-action
+overrides, link transitions, remote keys a title turns off, and 720p. This
+navigation is the one [oncemore](https://github.com/kajisho5/oncemore)
+writes, byte for byte. 0.4 adds pop-up menus over a playing title. Menus
+with motion or music come next.
 
 ## Why
 
@@ -75,6 +78,23 @@ disc.add_title("extras.m2ts", fps=(25, 1))
 disc.write("out")                       # out/BDMV/...
 ```
 
+A clip can carry several sound tracks, each from the video itself or from
+another file; track k is the title's audio track k (silence when a file has
+no sound, and sound shorter than the picture is made up with silence):
+
+```python
+from bdmvkit.encode import AudioTrack
+
+encode_clip("feature.mov", "feature.m2ts", audio=[
+    AudioTrack(),                                   # the video's own sound, AC-3
+    AudioTrack("commentary.wav", "lpcm"),           # another file, LPCM
+    AudioTrack("feature.mov", "ac3", 6, stream=1),  # its second sound stream, 5.1
+])
+disc.add_title("feature.m2ts", audio=[("ac3", 2, "en"), ("lpcm", 2, "en"), ("ac3", 6, "ja")])
+```
+
+`Disc.write` checks that every track a title declares is in its clip.
+
 A menu is a picture and its buttons. Each button is a picture of how it
 looks when selected (and, if given, when activated and before it is
 selected), placed on the 1920 x 1080 menu, and a link:
@@ -91,10 +111,44 @@ disc.add_menu("main", "menu.png", [
 disc.write("out")
 ```
 
-Links are `title:<n>`, `chapter:<n>:<c>` and `menu:<id>`; a title's `end`
-takes the same. The arrow keys go to the nearest button that way unless a
-button's `nav` says (`{"down": "scene2"}`). `bdmvkit.igs` makes the button
-stream on its own, for other tools.
+A button's `action`, a title's `end` and the disc's first play are
+actions: `title:<n>`, `chapter:<n>:<c>`, `playlist:<id>`, `playall`,
+`menu:<id>` (or `menu:<id>:<button>`, that button selected), `lastmenu`,
+`resume`, `audio:<n>`, `subtitle:<n>` or `subtitle:off`, and `stop`. The
+arrow keys go to the nearest button that way unless a button's `nav` says
+(`{"down": "scene2"}`). `bdmvkit.igs` makes the button stream on its own,
+for other tools.
+
+```python
+disc = Disc(title_key="menu:main")
+a = disc.add_title("feature.m2ts", chapters=[0, 300], audio=[("ac3", 6, "en"), ("ac3", 6, "ja")],
+                   subtitles=["en", "ja"], default_subtitle=1, end="lastmenu")
+n = disc.add_title("notice.m2ts", prohibit=["next", "fast_forward", "menu"], end="title:1")
+disc.add_playlist("both", [n, (a, 2, None)], order="shuffle", end="menu:main")
+disc.add_menu("main", "menu.png", [
+    MenuButton("play", 160, 700, "play.png", action="title:2"),          # the notice first
+    MenuButton("ja", 160, 800, "ja.png", action="title:1", audio=2, subtitle=0),
+    MenuButton("both", 160, 900, "both.png", action="playlist:both"),
+], loop=3, end="playall", seconds=10)
+```
+
+A title can have a pop-up menu: buttons over its picture, opened with the
+remote's Pop-up Menu key. Their pictures are placed on the 1920 x 1080 frame
+as a menu's are; a button that only switches the sound or subtitle track
+closes the menu.
+
+```python
+disc.add_popup(a, [
+    MenuButton("scenes", 160, 900, "scenes.png", "scenes-on.png", "scenes-off.png",
+               action="menu:main"),
+    MenuButton("ja", 560, 900, "ja.png", normal="ja-off.png", action="audio:2"),
+])
+```
+
+Underneath, `bdmvkit.program` describes a disc made of encoded clips
+(titles, playlists, menu clips that carry their buttons, transitions) and
+`bdmvkit.nav.write_program` writes it; `nav.Navigation` gives the commands a
+menu's buttons run, for tools that make their own IG streams.
 
 ```sh
 bdmvkit encode feature.mov feature.m2ts --chapters 0,300,600
@@ -115,12 +169,20 @@ bdmvkit build disc.json out
 How the disc is laid out:
 
 * Frame rates are 23.976 (1080p), 25 and 29.97. The last two are coded as
-  progressive frames in a 1080i stream, as the format asks.
+  progressive frames in a 1080i stream, as the format asks. A program can
+  also be 720p (23.976, 50, 59.94; 25 and 29.97 go on at twice their rate);
+  `encode_clip` makes 1080 clips.
 * Sound is AC-3, LPCM or DTS.
 * Subtitles are PGS streams muxed into the clip. `pgs.write_sup` makes them
   from pictures, and `encode_clip(..., sups=[...])` muxes them in.
 * First play and the Top Menu key open the first menu, or start title 1
-  when there is none.
+  when there is none (`Disc(first_play=..., title_key=...)` choose).
+* Each title, playlist, play all and menu is a Blu-ray title, in that
+  order; random and shuffled playlists play a playlist file per item, picked
+  with the player's random number command. The general registers 1 to 8
+  hold the last menu, the button a link selects, a menu's loop count, an
+  end-action override, a stream choice, and a random playlist's state
+  (`nav.py`).
 * A menu is an interactive title after the titles: its picture held as a
   still, with its buttons as an Interactive Graphics stream in its clip.
   The menus are encoded when the disc is written (ffmpeg).
@@ -144,7 +206,12 @@ The tests encode real clips, write a disc, and read it back with
 * that running the disc from first play reaches the titles and chapters in
   order;
 * that a menu's buttons, chosen and pressed with the remote's keys, start
-  the titles, chapters and menus they link to.
+  the titles, chapters, playlists and menus they link to, that a shuffled
+  playlist plays each item once, and that a menu with a loop count goes on
+  by itself;
+* that a pop-up menu opens over a playing title with the Pop-up Menu key and
+  its buttons start another title or a chapter;
+* the commands every kind of action, title, playlist and menu turns into.
 
 The files' fixed bytes are checked as well.
 

{bdmvkit-0.2.0 → bdmvkit-0.4.0}/README.md

@@ -18,11 +18,14 @@ only to encode.
 
 日本語の説明は [README.ja.md](README.ja.md) にあります。
 
-**Status: 0.2.** Titles with chapters, sound and subtitle tracks, and menus
-whose buttons start titles, chapters and other menus. Pop-up menus (over a
-playing title) and menus with motion or music come next; they already work
-in [oncemore](https://github.com/kajisho5/oncemore), where this code comes
-from.
+**Status: 0.4.** Titles with chapters, sound and subtitle tracks;
+playlists (in order, at random or shuffled) and play all; menus whose
+buttons start titles, chapters, playlists and other menus, switch sound and
+subtitle tracks, or open a menu on a chosen button; loop counts, end-action
+overrides, link transitions, remote keys a title turns off, and 720p. This
+navigation is the one [oncemore](https://github.com/kajisho5/oncemore)
+writes, byte for byte. 0.4 adds pop-up menus over a playing title. Menus
+with motion or music come next.
 
 ## Why
 
@@ -58,6 +61,23 @@ disc.add_title("extras.m2ts", fps=(25, 1))
 disc.write("out")                       # out/BDMV/...
 ```
 
+A clip can carry several sound tracks, each from the video itself or from
+another file; track k is the title's audio track k (silence when a file has
+no sound, and sound shorter than the picture is made up with silence):
+
+```python
+from bdmvkit.encode import AudioTrack
+
+encode_clip("feature.mov", "feature.m2ts", audio=[
+    AudioTrack(),                                   # the video's own sound, AC-3
+    AudioTrack("commentary.wav", "lpcm"),           # another file, LPCM
+    AudioTrack("feature.mov", "ac3", 6, stream=1),  # its second sound stream, 5.1
+])
+disc.add_title("feature.m2ts", audio=[("ac3", 2, "en"), ("lpcm", 2, "en"), ("ac3", 6, "ja")])
+```
+
+`Disc.write` checks that every track a title declares is in its clip.
+
 A menu is a picture and its buttons. Each button is a picture of how it
 looks when selected (and, if given, when activated and before it is
 selected), placed on the 1920 x 1080 menu, and a link:
@@ -74,10 +94,44 @@ disc.add_menu("main", "menu.png", [
 disc.write("out")
 ```
 
-Links are `title:<n>`, `chapter:<n>:<c>` and `menu:<id>`; a title's `end`
-takes the same. The arrow keys go to the nearest button that way unless a
-button's `nav` says (`{"down": "scene2"}`). `bdmvkit.igs` makes the button
-stream on its own, for other tools.
+A button's `action`, a title's `end` and the disc's first play are
+actions: `title:<n>`, `chapter:<n>:<c>`, `playlist:<id>`, `playall`,
+`menu:<id>` (or `menu:<id>:<button>`, that button selected), `lastmenu`,
+`resume`, `audio:<n>`, `subtitle:<n>` or `subtitle:off`, and `stop`. The
+arrow keys go to the nearest button that way unless a button's `nav` says
+(`{"down": "scene2"}`). `bdmvkit.igs` makes the button stream on its own,
+for other tools.
+
+```python
+disc = Disc(title_key="menu:main")
+a = disc.add_title("feature.m2ts", chapters=[0, 300], audio=[("ac3", 6, "en"), ("ac3", 6, "ja")],
+                   subtitles=["en", "ja"], default_subtitle=1, end="lastmenu")
+n = disc.add_title("notice.m2ts", prohibit=["next", "fast_forward", "menu"], end="title:1")
+disc.add_playlist("both", [n, (a, 2, None)], order="shuffle", end="menu:main")
+disc.add_menu("main", "menu.png", [
+    MenuButton("play", 160, 700, "play.png", action="title:2"),          # the notice first
+    MenuButton("ja", 160, 800, "ja.png", action="title:1", audio=2, subtitle=0),
+    MenuButton("both", 160, 900, "both.png", action="playlist:both"),
+], loop=3, end="playall", seconds=10)
+```
+
+A title can have a pop-up menu: buttons over its picture, opened with the
+remote's Pop-up Menu key. Their pictures are placed on the 1920 x 1080 frame
+as a menu's are; a button that only switches the sound or subtitle track
+closes the menu.
+
+```python
+disc.add_popup(a, [
+    MenuButton("scenes", 160, 900, "scenes.png", "scenes-on.png", "scenes-off.png",
+               action="menu:main"),
+    MenuButton("ja", 560, 900, "ja.png", normal="ja-off.png", action="audio:2"),
+])
+```
+
+Underneath, `bdmvkit.program` describes a disc made of encoded clips
+(titles, playlists, menu clips that carry their buttons, transitions) and
+`bdmvkit.nav.write_program` writes it; `nav.Navigation` gives the commands a
+menu's buttons run, for tools that make their own IG streams.
 
 ```sh
 bdmvkit encode feature.mov feature.m2ts --chapters 0,300,600
@@ -98,12 +152,20 @@ bdmvkit build disc.json out
 How the disc is laid out:
 
 * Frame rates are 23.976 (1080p), 25 and 29.97. The last two are coded as
-  progressive frames in a 1080i stream, as the format asks.
+  progressive frames in a 1080i stream, as the format asks. A program can
+  also be 720p (23.976, 50, 59.94; 25 and 29.97 go on at twice their rate);
+  `encode_clip` makes 1080 clips.
 * Sound is AC-3, LPCM or DTS.
 * Subtitles are PGS streams muxed into the clip. `pgs.write_sup` makes them
   from pictures, and `encode_clip(..., sups=[...])` muxes them in.
 * First play and the Top Menu key open the first menu, or start title 1
-  when there is none.
+  when there is none (`Disc(first_play=..., title_key=...)` choose).
+* Each title, playlist, play all and menu is a Blu-ray title, in that
+  order; random and shuffled playlists play a playlist file per item, picked
+  with the player's random number command. The general registers 1 to 8
+  hold the last menu, the button a link selects, a menu's loop count, an
+  end-action override, a stream choice, and a random playlist's state
+  (`nav.py`).
 * A menu is an interactive title after the titles: its picture held as a
   still, with its buttons as an Interactive Graphics stream in its clip.
   The menus are encoded when the disc is written (ffmpeg).
@@ -127,7 +189,12 @@ The tests encode real clips, write a disc, and read it back with
 * that running the disc from first play reaches the titles and chapters in
   order;
 * that a menu's buttons, chosen and pressed with the remote's keys, start
-  the titles, chapters and menus they link to.
+  the titles, chapters, playlists and menus they link to, that a shuffled
+  playlist plays each item once, and that a menu with a loop count goes on
+  by itself;
+* that a pop-up menu opens over a playing title with the Pop-up Menu key and
+  its buttons start another title or a chapter;
+* the commands every kind of action, title, playlist and menu turns into.
 
 The files' fixed bytes are checked as well.
 

{bdmvkit-0.2.0 → bdmvkit-0.4.0}/bdmvkit/__init__.py

@@ -1,7 +1,10 @@
 """bdmvkit: Blu-ray (BDMV) authoring in pure Python.
 
 * `bdmvkit.Disc`: a BDMV folder from encoded clips (titles, chapters, sound
-  and subtitle tracks, played in order) and menus (`MenuButton`).
+  and subtitle tracks), playlists, menus and pop-up menus (`MenuButton`).
+* `bdmvkit.program` and `bdmvkit.nav`: the model underneath (titles,
+  playlists, menu clips, transitions, actions) and its writer,
+  `nav.write_program`, with the navigation commands (`nav.Navigation`).
 * `bdmvkit.igs`: a menu's buttons as an Interactive Graphics stream.
 * `bdmvkit.encode.encode_clip`: a clip encoded for Blu-ray with ffmpeg + x264.
 * `bdmvkit.pgs`: PGS subtitle streams (.sup) from pictures.
@@ -12,5 +15,5 @@
 from .disc import Disc, MenuButton
 from .errors import BdmvError
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __all__ = ["Disc", "MenuButton", "BdmvError"]

{bdmvkit-0.2.0 → bdmvkit-0.4.0}/bdmvkit/__main__.py

@@ -9,7 +9,12 @@ DISC.json: {"titles": [{"clip": "a.m2ts", "fps": "24000/1001",
 "buttons": [{"id": "play", "x": 160, "y": 700, "selected": "play.png",
 "action": "title:1"}]}], "play_all": true}; paths are relative to the JSON
 file. A button may also have "activated" and "normal" pictures, "nav"
-({"up": id, ...}) and "auto"; a menu "default" (a button id) and "fps".
+({"up": id, ...}), "auto", "audio", "subtitle" and "override"; a menu
+"default" (a button id), "fps", "loop", "end", "seconds" and "prohibit"; a
+title "default_audio", "default_subtitle", "prohibit" and "popup" ({"buttons":
+[...], "default"}: its pop-up menu, buttons as a menu's). The disc may have
+"playlists" ([{"id", "items": [n or [n, first, last]], "order", "end"}]),
+"first_play" and "title_key".
 """
 
 import argparse
@@ -56,23 +61,35 @@ def main(argv=None):
         with open(args.disc, encoding="utf-8") as f:
             spec = json.load(f)
         base = os.path.dirname(os.path.abspath(args.disc))
-        disc = Disc()
+        disc = Disc(spec.get("first_play"), spec.get("title_key"))
         for t in spec.get("titles", []):
             disc.add_title(os.path.join(base, t["clip"]), fps=_fps(t.get("fps", "24000/1001")),
                            chapters=t.get("chapters", [0]),
                            audio=[tuple(a) for a in t.get("audio", [["ac3", 2, "und"]])],
-                           subtitles=t.get("subtitles", []), end=t.get("end"))
+                           subtitles=t.get("subtitles", []), end=t.get("end"),
+                           default_audio=t.get("default_audio"),
+                           default_subtitle=t.get("default_subtitle"),
+                           prohibit=t.get("prohibit", []))
+        for p in spec.get("playlists", []):
+            disc.add_playlist(p["id"], p["items"], p.get("order", "sequential"), p.get("end"))
 
         def file(name):
             return os.path.join(base, name) if name else None
 
+        def buttons(spec_buttons):
+            return [MenuButton(b["id"], int(b["x"]), int(b["y"]), file(b["selected"]),
+                               file(b.get("activated")), file(b.get("normal")), b.get("action"),
+                               dict(b.get("nav", {})), bool(b.get("auto")), b.get("audio"),
+                               b.get("subtitle"), b.get("override")) for b in spec_buttons]
+
+        for n, t in enumerate(spec.get("titles", []), 1):
+            if t.get("popup"):
+                disc.add_popup(n, buttons(t["popup"]["buttons"]), t["popup"].get("default"))
         for m in spec.get("menus", []):
-            disc.add_menu(m["id"], file(m["background"]), [
-                MenuButton(b["id"], int(b["x"]), int(b["y"]), file(b["selected"]),
-                           file(b.get("activated")), file(b.get("normal")), b.get("action"),
-                           dict(b.get("nav", {})), bool(b.get("auto")))
-                for b in m["buttons"]], fps=_fps(m.get("fps", "24000/1001")),
-                default=m.get("default"))
+            disc.add_menu(m["id"], file(m["background"]), buttons(m["buttons"]),
+                          fps=_fps(m.get("fps", "24000/1001")), default=m.get("default"),
+                          loop=m.get("loop"), end=m.get("end"), prohibit=m.get("prohibit", []),
+                          seconds=float(m.get("seconds", 1.0)))
         res = disc.write(args.out, play_all=spec.get("play_all", True), fast=args.fast)
     except (BdmvError, OSError, KeyError, ValueError) as e:
         print(f"bdmvkit: {getattr(e, 'message', e)}", file=sys.stderr)

bdmvkit-0.4.0/bdmvkit/disc.py

@@ -0,0 +1,281 @@
+"""A BDMV folder from encoded clips: titles with chapters, played from the
+first one on (or each on its own), with their sound and subtitle tracks.
+
+    disc = Disc()
+    disc.add_title("feature.m2ts", chapters=[0, 300, 600], audio=[("ac3", 6, "en")],
+                   subtitles=["en", "ja"])
+    disc.add_title("extras.m2ts")
+    disc.write("out")            # out/BDMV/...
+
+Each title is a playlist with a chapter mark at every chapter (on the key
+frame nearest to it: encode the clip with key frames there, as
+encode.encode_clip does) and a movie object that plays it. First play and
+the Top Menu key start title 1; with `play_all`, each title goes on to the
+next when it ends. Clips are BDAV streams with the PIDs formats.py names.
+
+Menus: a picture with buttons, each linked to a title, a chapter or
+another menu:
+
+    disc.add_menu("main", "menu.png", [
+        MenuButton("play", 160, 700, "play.png", action="title:1"),
+        MenuButton("scenes", 160, 800, "scenes.png", "scenes-lit.png", action="menu:scenes"),
+    ])
+    disc.add_title("feature.m2ts", end="menu:main")     # back to the menu at the end
+
+A button's pictures are its selected (and activated) look, drawn over the
+menu where it is; with a `normal` picture it is drawn there before it is
+selected too. The arrow keys go to the nearest button that way unless
+`nav` says otherwise. Each menu is an interactive title after the titles:
+its picture held as a still, its buttons an IG stream (igs.py) in its clip.
+With menus, first play and the Top Menu key open the first menu.
+"""
+
+import dataclasses
+import os
+import tempfile
+
+from . import encode, hdmv, igs, program
+from .errors import BdmvError
+from .formats import AUDIO_PID, CODECS, FORMATS, HEIGHT, PG_PID, WIDTH, lang3
+from .m2ts import stream_pids
+from .program import parse_action
+from .nav import DIRS, Navigation, _write, chapter_marks, write_program  # noqa: F401
+
+
+@dataclasses.dataclass
+class Title:
+    clip: str                    # an encoded .m2ts
+    fps: tuple = (24000, 1001)   # its frame rate: 24000/1001, 25/1 or 30000/1001
+    chapters: list = dataclasses.field(default_factory=lambda: [0.0])   # starts, seconds
+    audio: list = dataclasses.field(default_factory=lambda: [("ac3", 2, "und")])
+    subtitles: list = dataclasses.field(default_factory=list)          # PG tracks: languages
+    end: str = None              # the action after it (None: the next title with play_all)
+    default_audio: int = None    # the sound track the disc starts with (1-based)
+    default_subtitle: int = None  # the subtitle track shown when it starts (None: off)
+    prohibit: list = dataclasses.field(default_factory=list)           # uops.KEYS names
+
+
+@dataclasses.dataclass
+class MenuButton:
+    id: str
+    x: int                       # top-left on the 1920 x 1080 menu
+    y: int
+    selected: str                # picture files (PNG ...): selected,
+    activated: str = None        # activated (default: the selected one),
+    normal: str = None           # and before it is selected (default: nothing)
+    action: str = None           # where it goes: an action (program.py), e.g. "title:2"
+    nav: dict = dataclasses.field(default_factory=dict)    # direction -> button id
+    auto: bool = False           # runs as soon as it is selected
+    audio: int = None            # switch to this sound track (1-based) first
+    subtitle: int = None         # ... and to this subtitle track (0: off)
+    override: str = None         # the end action of the title it starts, instead of its own
+
+
+@dataclasses.dataclass
+class Menu:
+    id: str
+    background: str              # picture file, fitted into the HD frame
+    buttons: list
+    fps: tuple = (24000, 1001)
+    default: str = None          # the button selected first (default: the first)
+    loop: int = None             # held this many times its length, then `end`
+    end: str = None
+    prohibit: list = dataclasses.field(default_factory=list)
+    seconds: float = 1.0         # its clip's length
+
+
+def _check_streams(n, title):
+    """The title's sound and subtitle tracks must be in its clip, with the
+    PIDs the playlist gives them (encode.encode_clip makes them so)."""
+    pids = stream_pids(title.clip)
+    want = [("audio", AUDIO_PID, k) for k in range(len(title.audio))] + \
+        [("subtitle", PG_PID, k) for k in range(len(title.subtitles))]
+    for kind, first, k in want:
+        if first + k not in pids:
+            raise BdmvError(f"title {n}: {kind} track {k + 1} is not in {title.clip} "
+                            f"(no stream with PID {first + k:#06x})")
+
+
+class Disc:
+    """first_play: the action the disc starts with (default: the first menu,
+    or title 1); title_key: the Top Menu key's (default: the same)."""
+
+    def __init__(self, first_play=None, title_key=None):
+        self.titles = []
+        self.menus = []
+        self.playlists = []
+        self.popups = {}                 # title number -> (buttons, default)
+        self.first_play = first_play
+        self.title_key = title_key
+
+    def add_title(self, clip, fps=(24000, 1001), chapters=(0.0,), audio=(("ac3", 2, "und"),),
+                  subtitles=(), end=None, default_audio=None, default_subtitle=None,
+                  prohibit=()):
+        """Add a title; returns its number (1-based), its id in actions
+        ("title:2"). audio: (codec, channels, language) per track, codec
+        "ac3", "lpcm" or "dts"; languages are ISO 639-1 ("en") or 639-2
+        ("eng") codes. end: the action when it ends (default: the next title
+        with play_all). default_audio: the sound track the disc starts with;
+        default_subtitle: the subtitle track shown from its start (else
+        none); prohibit: remote keys it does not allow (uops.KEYS)."""
+        if tuple(fps) not in FORMATS:
+            raise BdmvError(f"{fps[0]}/{fps[1]} fps has no Blu-ray format")
+        for codec, _, _ in audio:
+            if codec not in CODECS:
+                raise BdmvError(f"unknown audio codec {codec!r} (ac3, lpcm or dts)")
+        if not audio:
+            raise BdmvError("a title needs at least one audio track")
+        for name, k, n in (("default_audio", default_audio, len(audio)),
+                           ("default_subtitle", default_subtitle, len(subtitles))):
+            if k is not None and not 1 <= k <= n:
+                raise BdmvError(f"{name} {k}: the title has {n} such tracks")
+        self.titles.append(Title(clip, tuple(fps), list(chapters) or [0.0], list(audio),
+                                 list(subtitles), end, default_audio, default_subtitle,
+                                 list(prohibit)))
+        return len(self.titles)
+
+    def add_playlist(self, playlist_id, items, order="sequential", end=None):
+        """Add a playlist: items (title, first chapter, last chapter), or
+        title numbers for whole titles, played one after another
+        ("sequential"), picked at random as many times as there are items
+        ("random"), or each once in a random order ("shuffle"). It is
+        started by "playlist:<id>"."""
+        if any(p.id == playlist_id for p in self.playlists):
+            raise BdmvError(f"there is a playlist {playlist_id!r} already")
+        out = []
+        for it in items:
+            n, first, last = (it, 1, None) if isinstance(it, int) else tuple(it) + (None,) * \
+                (3 - len(it))
+            out.append(program.PlaylistItem(str(n), first or 1, last))
+        self.playlists.append(program.Playlist(playlist_id, out, order, end))
+
+    def add_menu(self, menu_id, background, buttons, fps=(24000, 1001), default=None, loop=None,
+                 end=None, prohibit=(), seconds=1.0):
+        """Add a menu: `background` a picture, `buttons` MenuButtons. The
+        menu's clip (`seconds` long) is made when the disc is written
+        (ffmpeg). It holds its last picture; with `loop`, only for `loop`
+        times its length, then it does `end`."""
+        if tuple(fps) not in FORMATS:
+            raise BdmvError(f"{fps[0]}/{fps[1]} fps has no Blu-ray format")
+        if any(m.id == menu_id for m in self.menus):
+            raise BdmvError(f"there is a menu {menu_id!r} already")
+        if not buttons:
+            raise BdmvError(f"menu {menu_id!r} needs at least one button")
+        self.menus.append(Menu(menu_id, background, list(buttons), tuple(fps), default, loop,
+                               end, list(prohibit), seconds))
+
+    def add_popup(self, title, buttons, default=None):
+        """Give title `title` (its number) a pop-up menu: `buttons`
+        (MenuButtons, their pictures placed on the 1920 x 1080 picture over
+        the playing title) shown by the remote's Pop-up Menu key. A button
+        that switches the sound or subtitle track closes the menu; one that
+        goes elsewhere goes there. The menu's IG stream is muxed into the
+        title's clip when the disc is written."""
+        if not 1 <= title <= len(self.titles):
+            raise BdmvError(f"there is no title {title}")
+        if not buttons:
+            raise BdmvError(f"title {title}: a pop-up menu needs at least one button")
+        self.popups[title] = (list(buttons), default)
+
+    def program(self, play_all=True):
+        """The disc as a program.Program (titles "1", "2" ...; menus with no
+        clip yet: write makes them)."""
+        n_titles = len(self.titles)
+        titles = []
+        for n, t in enumerate(self.titles, 1):
+            end = t.end or (f"title:{n + 1}" if play_all and n < n_titles else None)
+            titles.append(program.Title(
+                str(n), t.clip, t.fps, list(t.chapters),
+                [program.Audio(CODECS[c], ch, _lang(lang), k == t.default_audio)
+                 for k, (c, ch, lang) in enumerate(t.audio, 1)],
+                [program.Subtitle(_lang(lang), k == t.default_subtitle)
+                 for k, lang in enumerate(t.subtitles, 1)], end, list(t.prohibit),
+                popup=n in self.popups,
+                popup_buttons=[_button(b) for b in self.popups.get(n, ((), None))[0]]))
+        menus = [program.Menu(m.id, None,
+                              [_button(b) for b in m.buttons],
+                              fps=m.fps, default=m.default, loop=m.loop, end=m.end,
+                              still_time=max(1, round(m.seconds)) if m.loop is not None
+                              else None,
+                              prohibit=list(m.prohibit)) for m in self.menus]
+        first_menu = f"menu:{self.menus[0].id}" if self.menus else None
+        return program.Program(titles, list(self.playlists), menus,
+                               first_play=self.first_play or first_menu,
+                               title_key=self.title_key)
+
+    def write(self, out_dir, move=False, play_all=True, fast=False):
+        """Write the BDMV folder into `out_dir` (copying the clips into
+        BDMV/STREAM, or moving them with `move`; menu clips are encoded,
+        quickly with `fast`). Returns {"titles", "menus", "playlists",
+        "chapters"}."""
+        if not self.titles:
+            raise BdmvError("a disc needs at least one title")
+        prog = self.program(play_all)
+        prog.check()                     # (the menus' clips are made below)
+        for n, t in enumerate(self.titles, 1):
+            _check_streams(n, t)
+        nav = Navigation(prog)
+        os.makedirs(os.path.join(out_dir, "BDMV", "STREAM"), exist_ok=True)
+        for k, (m, pm) in enumerate(zip(self.menus, prog.menus), len(self.titles) + 1):
+            pm.clip = os.path.join(out_dir, "BDMV", "STREAM", f"{k:05d}.m2ts")
+            self._encode_menu(m, pm, nav, fast)
+        for n, (buttons, default) in sorted(self.popups.items()):
+            pt = prog.titles[n - 1]
+            pt.clip = os.path.join(out_dir, "BDMV", "STREAM", f"{n:05d}.m2ts")
+            self._add_popup(self.titles[n - 1], buttons, default, pt, nav)
+        out = write_program(prog, out_dir, move=move)
+        return {"titles": len(self.titles), "menus": len(self.menus),
+                "playlists": out["playlists"], "chapters": out["chapters"]}
+
+    def _encode_menu(self, m, pm, nav, fast):
+        """Menu `m`'s clip (pm.clip): its buttons' pictures read, the IG
+        stream made with their commands and encoded with its picture."""
+        buttons = _ig_buttons(f"menu {m.id!r}", m.buttons, pm.buttons, nav)
+        _, frame_rate = FORMATS[m.fps]
+        with tempfile.TemporaryDirectory(prefix="bdmvkit-") as work:
+            sup = os.path.join(work, "menu.sup")
+            with open(sup, "wb") as f:
+                f.write(igs.ig_stream(buttons, frame_rate, default=m.default,
+                                      follow_selection=nav.follows_selection(m.id)))
+            encode.encode_menu(m.background, sup, pm.clip, m.fps, seconds=m.seconds, fast=fast)
+
+
+    def _add_popup(self, t, buttons, default, pt, nav):
+        """The title's clip with its pop-up menu's IG stream, as pt.clip."""
+        _, frame_rate = FORMATS[t.fps]
+        ig = _ig_buttons(f"title {pt.id}'s pop-up menu", buttons, pt.popup_buttons, nav,
+                         popup=True)
+        with tempfile.TemporaryDirectory(prefix="bdmvkit-") as work:
+            sup = os.path.join(work, "popup.sup")
+            with open(sup, "wb") as f:
+                f.write(igs.ig_stream(ig, frame_rate, default=default, popup=True))
+            encode.add_ig_stream(t.clip, sup, pt.clip)
+
+
+def _button(b):
+    return program.Button(b.id, b.action, b.audio, b.subtitle, override=b.override)
+
+
+def _ig_buttons(where, buttons, program_buttons, nav, popup=False):
+    """MenuButtons as igs.Buttons: their pictures read, their commands the
+    navigation's (in a pop-up menu, a button that only switches streams
+    closes the menu too)."""
+    out = []
+    for b, pb in zip(buttons, program_buttons):
+        w, h, sel = encode.picture(b.selected)
+        if b.x < 0 or b.y < 0 or b.x + w > WIDTH or b.y + h > HEIGHT:
+            raise BdmvError(f"{where}: button {b.id!r} ({w} x {h} at {b.x}, {b.y}) "
+                            f"is not inside the {WIDTH} x {HEIGHT} frame")
+        act = encode.picture(b.activated, (w, h))[2] if b.activated else None
+        nor = encode.picture(b.normal, (w, h))[2] if b.normal else None
+        commands = nav.button(pb) if b.action else []
+        if popup and b.action and parse_action(b.action)[0] in ("audio", "subtitle"):
+            commands.append(hdmv.popup_off())
+        out.append(igs.Button(b.id, b.x, b.y, w, h, sel, act, nor, commands, dict(b.nav),
+                              b.auto))
+    return out
+
+
+def _lang(code):
+    code = (code or "").lower()
+    return code if len(code) == 3 and code.isalpha() else lang3(code)