Video Description Builder

Most people treat the box under a video as an afterthought: a few lines typed after the upload, when the real work feels done. Yet that box does three jobs at once. It is a map, because a list of times turns a long video into places a viewer can jump to. It is a label, because its first lines are what someone reads before deciding to stay. And it is a receipt, because it is where the creator says who made what, whose music played, and who paid for what.

Each job has rules, and the rules are small enough to get wrong without noticing. This essay walks through them in the order a careful writer meets them, and it is honest about which rules come from a published source and which are simply sensible habits.

The map: chapters rest on one tiny format

The platform’s developer reference for the Videos resource, read on 2026-10-20 under a Creative Commons licence, says two useful things about the description. Its maximum length is 5,000 bytes, and it may hold any valid UTF-8 character except the angle brackets. It also says that chapters are created by putting formatted timestamps, such as 00:00, into the description text. That is the whole of what the page says about chapters.

Everything else people repeat about chapters, a first chapter at zero, a minimum number of them, a minimum length for each, does not appear on that page. The tool therefore treats those as your settings. It starts them at its own defaults, three chapters of at least ten seconds with the first at zero, and says plainly that the current rules should be confirmed on the platform itself. A default that looks official but is not is worse than an honest blank.

The timestamp itself deserves more care than it gets. Two numbers joined by a colon mean minutes and seconds, so 1:05 is 65 seconds. Three numbers mean hours, minutes and seconds. A reader that guesses gets this wrong in the most damaging way: it reads 1:05 as an hour and five minutes, and a chapter meant for the second minute lands in the second hour. The checks behind this page include exactly that mistake, deliberately planted in a copy of the reader, and the test catches it.

So the reader is strict, and it says why it refuses. A bare 65 is ambiguous. 1:5 has a one digit seconds field. 1:61 is not a time at all, since seconds stop at 59. A minus sign, a decimal fraction, a full width colon or a digit from another script are all refused by name. Formatting is chosen once for the whole list: if any chapter passes the hour mark, every row shows hours, so the column reads cleanly.

None of these checks is clever. Each is a rule written down, applied the same way every time, and shown to you with its reason.

Chapters also have a shape that has nothing to do with any one platform. The W3C specification for WebVTT, the text track format browsers use for captions and chapters, describes chapter cues as consecutive, non overlapping intervals that mark up a timeline. That gives the structural rules for free: times must go up, no two chapters may start at the same second, and each chapter ends where the next begins.

The same specification fixes how a cue time is written, with two digit minutes and seconds and three digits of thousandths, and requires every cue to end after it starts. That is why the page can export a chapter file that a browser will accept, and why it needs the video length to give the last chapter an end.

The label: the first lines carry the weight

A description is often shown shortened, with a control that opens the rest, so the opening sentence has to do most of the work on its own. It should say what the video is, in the words someone would use to look for it, before any links, credits or hashtags crowd in.

How many lines are visible depends on the device, the app, the font size and the width of the screen, and no published source this page could use states it. The preview here is therefore an approximation and labelled as one. It measures each word in a neutral font with the canvas measureText method, which reports how wide a string will be drawn, wraps greedily at widths you choose, and draws a dashed line after the number of lines you set. It shows the shape of the problem rather than a promise of what any phone will display.

The fold matters for a second reason, which the US Federal Trade Commission spells out. Its staff guide for creators says a disclosure is likely to be missed if it sits anywhere a person has to click a more control to see. So the page checks, at each preview width, whether the disclosure starts above the fold, and it orders the blocks so that you decide which matters most.

The receipt: credits and disclosures

Credits are easy to skip and expensive to get wrong. A music licence often requires attribution, and the Creative Commons guidance on attribution suggests four parts: the title, the author, the source and the licence. The tool writes music lines in that order. It also says the obvious thing that is easy to forget: a licence may ask for its own wording, and where it does, the licence text wins over any template.

Disclosure is where the stakes are highest, and the page names the jurisdiction it follows: the United States. FTC staff guidance says to disclose any financial, employment, personal or family relationship with a brand, and that free or discounted products count as well as money. Plain words such as ad or sponsored are often enough; vague tags are not. It also says that for a video, the disclosure belongs in the video itself and not only in the description, and that affiliate links should be disclosed both in the video and in the description near the links. Rules in other countries differ, and this page does not pretend to cover them.

So the disclosure block is the one field you cannot skip. Before the description can be copied you must answer: none, or one or more of paid promotion, affiliate links and gifted products. The wording it writes is short and literal. If the affiliate note sits after the links, a check says so. None of this is legal advice; it is a way of making sure the question is asked every time.

Links get a quieter kind of honesty. Each address is read as text by the browser’s own URL parser, which follows the WHATWG URL Standard. Nothing is opened or fetched. The page lists any tracking parameters it finds, the five UTM names and the common click identifiers, so you can decide whether a viewer should carry your campaign tags around. It also flags an address that is not https.

Counting when the limit is in bytes

A limit stated in bytes behaves differently from one stated in characters, and a description is exactly the place where the difference shows. UTF-8, defined in RFC 3629, spends one byte on each basic Latin letter, two on most accented letters, three on most Chinese, Japanese and Korean characters and four on characters beyond the basic plane, such as many emoji. The RFC’s own examples make the point: three Korean syllables take nine bytes.

What a person calls one character can be several code points. A family emoji of three people is three pictures joined by two invisible joiners. The browser’s segmenter, which splits text into graphemes, counts it as one character. JavaScript’s length property, which counts UTF-16 code units, counts eight. In UTF-8 it costs 18 bytes. A text full of such characters can sit comfortably under a limit of 5,000 characters and still be refused at 5,000 bytes.

That is why the page counts three ways at once, characters as seen, UTF-16 units and UTF-8 bytes, and lets you choose which one your limit uses. The default is bytes, because that is the unit the API reference names. The checks compare the byte count with the browser’s own encoder on thousands of mixed strings, and confirm the RFC examples exactly.

A worked example

The example that loads with the page describes a video about repotting a houseplant, 13:20 long, with seven chapters. The soil chapter starts at 6:30 and the next at 9:12, so it lasts two minutes and forty two seconds. Divide 162 seconds by the video’s 800 and you get 20.3 percent, which is what the table and the timeline show.

The assembled text puts a one line affiliate note first, then the opening, the chapters, three links, the credits, a closing question and three hashtags. It comes to 834 bytes, well inside the 5,000 byte maximum. Every character in it is plain ASCII, so the three counts agree; paste in a family emoji and watch them part ways. One link carries two UTM parameters, and one uses plain http; both are flagged, neither is changed until you ask.

Now add a 15 second intro. Shifting every chapter later by 0:15 moves the first to 0:15, and the first chapter check fails until you add a new chapter at zero. Try shifting earlier by the same amount instead and the page refuses: the first chapter would start at minus fifteen seconds, and a shift that would put any chapter before the video begins is refused, never quietly clamped.

The page cannot say what any phone will show above the fold, what the platform will accept today, whether a disclosure is legally enough in your situation, or whether a description will bring a single extra view. It has no viewing data and makes no request. It can make the text correct by rules it states, readable in the places that matter, and honest about money and credit. For text that sits under every video you publish, that is most of the job.

The exports are deliberately plain: the description as text, the chapters as WebVTT and as CSV with a guard against cells a spreadsheet would run as formulas, and the whole state as JSON that opens again. Each is read back by a strict reader in the checks, because a file that cannot be read back is only a promise.