-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathguide.html
More file actions
497 lines (453 loc) · 34.6 KB
/
Copy pathguide.html
File metadata and controls
497 lines (453 loc) · 34.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Mosaic Guide & FAQ — Install, ffmpeg Setup, Output Types</title>
<meta name="description" content="How to install Mosaic, set up ffmpeg and MediaInfo, and use each output type. Answers on code signing, auto-update and supported video formats.">
<link rel="canonical" href="https://mosaicvideo.github.io/guide.html">
<meta name="theme-color" content="#060807">
<meta property="og:type" content="article">
<meta property="og:site_name" content="Mosaic">
<meta property="og:url" content="https://mosaicvideo.github.io/guide.html">
<meta property="og:title" content="Mosaic Guide & FAQ — Install, ffmpeg Setup, Output Types">
<meta property="og:description" content="How to install Mosaic, set up ffmpeg and MediaInfo, and use each output type. Answers on code signing, auto-update and supported video formats.">
<meta property="og:image" content="https://mosaicvideo.github.io/assets/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Mosaic — batch video thumbnailer for macOS, Windows and Linux">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Mosaic Guide & FAQ — Install, ffmpeg Setup, Output Types">
<meta name="twitter:description" content="How to install Mosaic, set up ffmpeg and MediaInfo, and use each output type. Answers on code signing, auto-update and supported video formats.">
<meta name="twitter:image" content="https://mosaicvideo.github.io/assets/og-image.png">
<meta name="twitter:image:alt" content="Mosaic — batch video thumbnailer for macOS, Windows and Linux">
<link rel="icon" type="image/png" href="assets/favicon.png">
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
<link rel="stylesheet" href="assets/style.css">
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"url": "https://mosaicvideo.github.io/guide.html",
"mainEntity": [
{
"@type": "Question",
"name": "Do I really need ffmpeg separately? Why isn't it bundled?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Bundling ffmpeg triples the installer size and locks you into whatever build options we picked. We recommend ffmpeg-full (which ships with libfreetype + libzimg for drawtext and HDR tonemapping). Keeping ffmpeg external lets you upgrade it independently. The app checks for ffmpeg and ffprobe on your PATH at startup. If either is missing, you'll see install instructions and a Retry button."
}
},
{
"@type": "Question",
"name": "macOS says \"Apple could not verify Mosaic is free of malware\"",
"acceptedAnswer": {
"@type": "Answer",
"text": "From v0.1.2 onward, macOS builds are Developer-ID signed and notarized. You should not see this warning. If you do on a very recent macOS: Make sure you're on v0.1.2 or later (check the window title — it shows the version). Right-click the app once → Open. Subsequent launches are fine. If the issue persists, file an issue — this shouldn't happen."
}
},
{
"@type": "Question",
"name": "Windows SmartScreen blocks the installer",
"acceptedAnswer": {
"@type": "Answer",
"text": "Windows builds aren't code-signed yet (EV certificates are expensive). SmartScreen warns until enough users download and confirm the file is safe. Click More info → Run anyway. Source is open on GitHub, releases are built by GitHub Actions from tagged commits — you can verify the build chain."
}
},
{
"@type": "Question",
"name": "Where are my output files saved?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Two choices in the output row at the bottom of the app: Next to source — outputs land in the same folder as each video, with a suffix (e.g. myvideo_sheet.jpg). Best for processing a single folder in place. Custom folder — all outputs go into one folder you pick. Best for batch runs across multiple source folders. Filenames follow {sourcename}{suffix}.{ext}. Collisions get a (1), (2) numeric suffix so nothing is overwritten."
}
},
{
"@type": "Question",
"name": "How does the auto-update work? When is it checked?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Once on every app launch, from v0.1.2 onward. Mosaic asks GitHub whether a newer release exists; if one does, a native dialog offers to install it. Accepting downloads the new version, verifies its cryptographic signature against a public key embedded in the app, installs, and relaunches — no manual download or re-install. Zero telemetry. The only request is an unauthenticated fetch of the public latest.json from this GitHub repo; nothing about your videos is ever sent. See Auto-update for the full flow."
}
},
{
"@type": "Question",
"name": "Can I cancel a job mid-way?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. Click Cancel in the action bar. The currently-running ffmpeg process is killed; files already completed are kept, in-flight files are cleaned up."
}
},
{
"@type": "Question",
"name": "My HDR video produces weird colors — what version of ffmpeg do I need?",
"acceptedAnswer": {
"@type": "Answer",
"text": "HDR tonemapping (HDR10, HLG) requires ffmpeg built with libzimg (the zscale filter). The default Homebrew ffmpeg on macOS lacks it — install ffmpeg-full instead, with `brew install ffmpeg-full`. Mosaic prefers ffmpeg-full automatically when present. For Dolby Vision Profile 5, a built-in IPT-PQ-C2 → BT.709 color correction runs regardless of ffmpeg build — no zscale required."
}
},
{
"@type": "Question",
"name": "Do I need to install MediaInfo too?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. Mosaic uses MediaInfo both to build richer contact-sheet headers (HDR format, commercial audio codec name, channel layout, language) and to power the per-file metadata viewer. Mosaic checks for mediainfo on your PATH at startup and shows the same \"required tools not found\" message as it does for missing ffmpeg. Installation is a one-liner per platform: brew install mediainfo on macOS, winget install MediaArea.MediaInfo.CLI on Windows, or apt install mediainfo on Debian and Ubuntu. See Requirements for the full list."
}
},
{
"@type": "Question",
"name": "Which video formats are supported?",
"acceptedAnswer": {
"@type": "Answer",
"text": "45 container types — anything ffmpeg can decode. This includes common formats (MP4, MKV, MOV, AVI, WebM, M4V), broadcast (MXF, R3D), transport streams (TS, M2TS), camcorder formats (DV, WTV), and legacy containers. If ffmpeg can probe it, Mosaic can process it."
}
},
{
"@type": "Question",
"name": "How big are the output files?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Depends on output type and settings: Contact sheets: 200 KB – 5 MB (JPEG 80–95% quality, 1920×wide). Screenshots: 50 KB – 2 MB each at full width. Animated previews (WebP): 500 KB – 10 MB for a few seconds of motion. Animated contact sheets: 1 – 20 MB depending on grid size and clip length. All dimensions and quality are configurable in settings."
}
},
{
"@type": "Question",
"name": "Does Mosaic upload my videos anywhere?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No. Everything happens locally via ffmpeg. The only network activity is the auto-update check — a single GET to GitHub's public releases API. No analytics, no telemetry, no cloud component, no account."
}
}
]
}
</script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Mosaic",
"item": "https://mosaicvideo.github.io/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Guide & FAQ",
"item": "https://mosaicvideo.github.io/guide.html"
}
]
}
</script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Mosaic manual — install, output types and FAQ",
"url": "https://mosaicvideo.github.io/guide.html",
"about": {
"@type": "SoftwareApplication",
"name": "Mosaic"
},
"publisher": {
"@type": "Organization",
"name": "Mosaic",
"url": "https://mosaicvideo.github.io/",
"sameAs": [
"https://github.com/mosaicvideo/mosaic"
]
}
}
</script>
</head>
<body>
<nav class="nav">
<div class="nav-inner">
<a href="./" class="nav-brand">
<span class="nav-brand-text">mosaic</span>
<span class="nav-brand-version" id="nav-version">v0.1.6</span>
</a>
<div class="nav-links">
<a href="guide.html" class="active">guide</a>
<a href="cli.html">cli</a>
<a href="#faq">faq</a>
<a href="https://github.com/mosaicvideo/mosaic/blob/main/CHANGELOG.md">log</a>
<a href="https://github.com/mosaicvideo/mosaic">git</a>
</div>
</div>
</nav>
<main>
<div class="container">
<div class="guide-layout">
<aside class="guide-toc" aria-label="Table of contents">
<div class="guide-toc-heading">Contents</div>
<ul>
<li><a href="#install">Install</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#first-run">First run</a></li>
<li><a href="#output-types">Output types</a>
<ul>
<li><a href="#contact-sheets">Contact sheets</a></li>
<li><a href="#screenshots">Screenshots</a></li>
<li><a href="#animated-previews">Animated previews</a></li>
</ul>
</li>
<li><a href="#settings">Settings</a></li>
<li><a href="#mediainfo">MediaInfo viewer</a></li>
<li><a href="#auto-update">Auto-update</a></li>
<li><a href="#cli">Command-line (CLI)</a></li>
<li><a href="#faq">FAQ</a></li>
</ul>
</aside>
<article class="guide-content">
<h1>mosaic manual</h1>
<p class="lede">Install in under a minute, skim the output types, then batch. FAQ at the bottom covers the common friction points — ffmpeg, Gatekeeper, SmartScreen, and the rest.</p>
<h2 id="install">Install</h2>
<p>Pick the package for your platform. All builds live on the <a href="https://github.com/mosaicvideo/mosaic/releases/latest">GitHub releases page</a>.</p>
<details class="platform" open>
<summary><span class="platform-icon"><svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12.152 6.896c-.948 0-2.415-1.078-3.96-1.04-2.04.027-3.91 1.183-4.961 3.014-2.117 3.675-.546 9.103 1.519 12.09 1.013 1.454 2.208 3.09 3.792 3.039 1.52-.065 2.09-.987 3.935-.987 1.831 0 2.35.987 3.96.948 1.637-.026 2.676-1.48 3.676-2.948 1.156-1.688 1.636-3.325 1.662-3.415-.039-.013-3.182-1.221-3.22-4.857-.026-3.04 2.48-4.494 2.597-4.559-1.429-2.09-3.623-2.324-4.39-2.376-2-.156-3.675 1.09-4.61 1.09zM15.53 3.83c.843-1.012 1.4-2.427 1.245-3.83-1.207.052-2.662.805-3.532 1.818-.78.896-1.454 2.338-1.273 3.714 1.338.104 2.715-.688 3.559-1.701"/></svg></span> macOS — universal</summary>
<div class="platform-body">
<ol>
<li>Download <code>Mosaic_universal.dmg</code>.</li>
<li>Open the DMG, drag <strong>Mosaic</strong> to <strong>Applications</strong>.</li>
<li>Launch from Applications or Spotlight.</li>
</ol>
<p>Works natively on both Apple Silicon and Intel.</p>
</div>
</details>
<details class="platform">
<summary><span class="platform-icon"><svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M0 3.449L9.75 2.1v9.451H0m10.949-9.602L24 0v11.4H10.949M0 12.6h9.75v9.451L0 20.699M10.949 12.6H24V24l-13.051-1.801"/></svg></span> Windows — x64 or ARM64</summary>
<div class="platform-body">
<ol>
<li>Download one of:
<ul>
<li><code>Mosaic_x64-setup.exe</code> — recommended, smaller installer</li>
<li><code>Mosaic_x64_en-US.msi</code> — MSI for enterprise / deployment tools</li>
<li><code>Mosaic_arm64-setup.exe</code> — for Snapdragon / ARM devices</li>
</ul>
</li>
<li>Run the installer.</li>
</ol>
<div class="callout warn">
<strong>SmartScreen will warn:</strong> "Windows protected your PC". Click <strong>More info</strong> → <strong>Run anyway</strong>. Windows builds aren't code-signed yet; the app is safe — verify the source on <a href="https://github.com/mosaicvideo/mosaic">GitHub</a>.
</div>
</div>
</details>
<details class="platform">
<summary><span class="platform-icon"><svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><path d="M12.504 0c-.155 0-.315.008-.48.021-4.226.333-3.105 4.807-3.17 6.298-.076 1.092-.3 1.953-1.05 3.02-.885 1.051-2.127 2.75-2.716 4.521-.278.832-.41 1.684-.287 2.489a.424.424 0 00-.11.135c-.26.268-.45.6-.663.839-.199.199-.485.267-.797.4-.313.136-.658.269-.864.68-.09.189-.136.394-.132.602 0 .199.027.4.055.536.058.399.116.728.04.97-.249.68-.28 1.145-.106 1.484.174.334.535.47.94.601.81.2 1.91.135 2.774.6.926.466 1.866.67 2.616.47.526-.116.97-.464 1.208-.946.587-.003 1.23-.269 2.26-.334.699-.058 1.574.267 2.577.2.025.134.063.198.114.333l.003.003c.391.778 1.113 1.132 1.884 1.071.771-.06 1.592-.536 2.257-1.306.631-.765 1.683-1.084 2.378-1.503.348-.199.629-.469.649-.853.023-.4-.2-.811-.714-1.376v-.097l-.003-.003c-.17-.2-.25-.535-.338-.926-.085-.401-.182-.786-.492-1.046h-.003c-.059-.054-.123-.067-.188-.135a.357.357 0 00-.19-.064c.431-1.278.264-2.55-.173-3.694-.533-1.41-1.465-2.638-2.175-3.483-.796-1.005-1.576-1.957-1.56-3.368.026-2.152.236-6.133-3.544-6.139zm.529 3.405h.013c.213 0 .396.062.584.198.19.135.33.332.438.533.105.259.158.459.166.724 0-.02.006-.04.006-.06v.105a.086.086 0 01-.004-.021l-.004-.024a1.807 1.807 0 01-.15.706.953.953 0 01-.213.335.71.71 0 00-.088-.042c-.104-.045-.198-.064-.284-.133a1.312 1.312 0 00-.22-.066c.05-.06.146-.133.183-.198.053-.128.082-.264.088-.402v-.02a1.21 1.21 0 00-.061-.4c-.045-.134-.101-.2-.183-.333-.084-.066-.167-.132-.267-.132h-.016c-.093 0-.176.03-.262.132a.8.8 0 00-.205.334 1.18 1.18 0 00-.09.4v.019c.002.089.008.179.02.267-.193-.067-.438-.135-.607-.202a1.635 1.635 0 01-.018-.2v-.02a1.772 1.772 0 01.15-.768c.082-.22.232-.406.43-.533a.985.985 0 01.594-.2zm-2.962.059h.036c.142 0 .27.048.399.135.146.129.264.288.344.465.09.199.14.4.153.667v.004c.007.134.006.2-.002.266v.08c-.03.007-.056.018-.083.024-.152.055-.274.135-.393.2.012-.09.013-.18.003-.267v-.015c-.012-.133-.04-.2-.082-.333a.613.613 0 00-.166-.267.248.248 0 00-.183-.064h-.021c-.071.006-.13.04-.186.132a.552.552 0 00-.12.27.944.944 0 00-.023.33v.015c.012.135.037.2.08.334.046.134.098.2.166.268.01.009.02.018.034.024-.07.057-.117.07-.176.136a.304.304 0 01-.131.068 2.62 2.62 0 01-.275-.402 1.772 1.772 0 01-.155-.667 1.759 1.759 0 01.08-.668 1.43 1.43 0 01.283-.535c.128-.133.26-.2.418-.2zm1.37 1.706c.332 0 .733.065 1.216.399.293.2.523.269 1.052.468h.003c.255.136.405.266.478.399v-.131a.571.571 0 01.016.47c-.123.31-.516.643-1.063.842v.002c-.268.135-.501.333-.775.465-.276.135-.588.292-1.012.267a1.139 1.139 0 01-.448-.067 3.566 3.566 0 01-.322-.198c-.195-.135-.363-.332-.612-.465v-.005h-.005c-.4-.246-.616-.512-.686-.71-.07-.268-.005-.47.193-.6.224-.135.38-.271.483-.336.104-.074.143-.102.176-.131h.002v-.003c.169-.202.436-.47.839-.601.139-.036.294-.065.466-.065zm2.8 2.142c.358 1.417 1.196 3.475 1.735 4.473.286.534.855 1.659 1.102 3.024.156-.005.33.018.513.064.646-1.671-.546-3.467-1.089-3.966-.22-.2-.232-.335-.123-.335.59.534 1.365 1.572 1.646 2.757.13.535.16 1.104.021 1.67.067.028.135.06.205.067 1.032.534 1.413.938 1.23 1.537v-.043c-.06-.003-.12 0-.18 0h-.016c.151-.467-.182-.825-1.065-1.224-.915-.4-1.646-.336-1.77.465-.008.043-.013.066-.018.135-.068.023-.139.053-.209.064-.43.268-.662.669-.793 1.187-.13.533-.17 1.156-.205 1.869v.003c-.02.334-.17.838-.319 1.35-1.5 1.072-3.58 1.538-5.348.334a2.645 2.645 0 00-.402-.533 1.45 1.45 0 00-.275-.333c.182 0 .338-.03.465-.067a.615.615 0 00.314-.334c.108-.267 0-.697-.345-1.163-.345-.467-.931-.995-1.788-1.521-.63-.4-.986-.87-1.15-1.396-.165-.534-.143-1.085-.015-1.645.245-1.07.873-2.11 1.274-2.763.107-.065.037.135-.408.974-.396.751-1.14 2.497-.122 3.854a8.123 8.123 0 01.647-2.876c.564-1.278 1.743-3.504 1.836-5.268.048.036.217.135.289.202.218.133.38.333.59.465.21.201.477.335.876.335.039.003.075.006.11.006.412 0 .73-.134.997-.268.29-.134.52-.334.74-.4h.005c.467-.135.835-.402 1.044-.7zm2.185 8.958c.037.6.343 1.245.882 1.377.588.134 1.434-.333 1.791-.765l.211-.01c.315-.007.577.01.847.268l.003.003c.208.199.305.53.391.876.085.4.154.78.409 1.066.486.527.645.906.636 1.14l.003-.007v.018l-.003-.012c-.015.262-.185.396-.498.595-.63.401-1.746.712-2.457 1.57-.618.737-1.37 1.14-2.036 1.191-.664.053-1.237-.2-1.574-.898l-.005-.003c-.21-.4-.12-1.025.056-1.69.176-.668.428-1.344.463-1.897.037-.714.076-1.335.195-1.814.12-.465.308-.797.641-.984l.045-.022zm-10.814.049h.01c.053 0 .105.005.157.014.376.055.706.333 1.023.752l.91 1.664.003.003c.243.533.754 1.064 1.189 1.637.434.598.77 1.131.729 1.57v.006c-.057.744-.48 1.148-1.125 1.294-.645.135-1.52.002-2.395-.464-.968-.536-2.118-.469-2.857-.602-.369-.066-.61-.2-.723-.4-.11-.2-.113-.602.123-1.23v-.004l.002-.003c.117-.334.03-.752-.027-1.118-.055-.401-.083-.71.043-.94.16-.334.396-.4.69-.533.294-.135.64-.202.915-.47h.002v-.002c.256-.268.445-.601.668-.838.19-.201.38-.336.663-.336zm7.159-9.074c-.435.201-.945.535-1.488.535-.542 0-.97-.267-1.28-.466-.154-.134-.28-.268-.373-.335-.164-.134-.144-.333-.074-.333.109.016.129.134.199.2.096.066.215.2.36.333.292.2.68.467 1.167.467.485 0 1.053-.267 1.398-.466.195-.135.445-.334.648-.467.156-.136.149-.267.279-.267.128.016.034.134-.147.332a8.097 8.097 0 01-.69.468zm-1.082-1.583V5.64c-.006-.02.013-.042.029-.05.074-.043.18-.027.26.004.063 0 .16.067.15.135-.006.049-.085.066-.135.066-.055 0-.092-.043-.141-.068-.052-.018-.146-.008-.163-.065zm-.551 0c-.02.058-.113.049-.166.066-.047.025-.086.068-.14.068-.05 0-.13-.02-.136-.068-.01-.066.088-.133.15-.133.08-.031.184-.047.259-.005.019.009.036.03.03.05v.02h.003z"/></svg></span> Linux — x64</summary>
<div class="platform-body">
<p>Three package formats — pick whichever suits your distro:</p>
<ul>
<li><strong>AppImage</strong> — portable, works on most distros:
<pre><code>chmod +x Mosaic_*_amd64.AppImage
./Mosaic_*_amd64.AppImage</code></pre>
</li>
<li><strong>.deb</strong> — Debian / Ubuntu / Mint:
<pre><code>sudo dpkg -i Mosaic_*_amd64.deb</code></pre>
</li>
<li><strong>.rpm</strong> — Fedora / RHEL / openSUSE:
<pre><code>sudo rpm -i Mosaic-*.x86_64.rpm</code></pre>
</li>
</ul>
</div>
</details>
<h2 id="requirements">Requirements</h2>
<p>Mosaic shells out to two external CLIs, both required: <strong>ffmpeg</strong> (with <code>ffprobe</code>) for extraction and tonemapping, and <strong><a href="https://mediaarea.net/en/MediaInfo">MediaInfo</a></strong> for richer header metadata (HDR format, commercial audio codec name, channel layout, language) and the per-file metadata viewer (see <a href="#mediainfo">below</a>). All three binaries — <code>ffmpeg</code>, <code>ffprobe</code>, <code>mediainfo</code> — must be on your <code>PATH</code>.</p>
<h3 class="minor">macOS</h3>
<pre><code>brew install ffmpeg-full mediainfo</code></pre>
<p>The default <code>brew install ffmpeg</code> bottle omits libfreetype and libzimg — required for text overlays and HDR tonemapping. <code>ffmpeg-full</code> has both; Mosaic automatically prefers it when installed.</p>
<h3 class="minor">Windows</h3>
<pre><code>winget install Gyan.FFmpeg MediaArea.MediaInfo.CLI</code></pre>
<p>Or via <a href="https://chocolatey.org/">Chocolatey</a>: <code>choco install ffmpeg-full mediainfo-cli</code>.</p>
<h3 class="minor">Linux</h3>
<pre><code>sudo apt install ffmpeg mediainfo # Debian / Ubuntu
sudo dnf install ffmpeg mediainfo # Fedora
sudo pacman -S ffmpeg mediainfo # Arch</code></pre>
<p>Most distro packages already ship ffmpeg with libfreetype and libzimg enabled.</p>
<h2 id="first-run">First run</h2>
<ol>
<li><strong>Drop videos.</strong> Drag files onto the window or click <em>Add Files</em> / <em>Add Folder</em>. Folders scan recursively.</li>
<li><strong>Pick output types.</strong> Check one or more: Screenshots, Contact Sheet, Animated Preview, Animated Contact Sheet.</li>
<li><strong>Choose output location.</strong> Either next to each source file or a single custom folder.</li>
<li><strong>Click Generate.</strong> Watch progress per file; cancel any time.</li>
</ol>
<figure class="showcase" style="margin: 2em 0;">
<img class="optional-screenshot" src="assets/screenshots/hero.webp" alt="Mosaic main window with a queue" width="1600" height="1197" loading="lazy" decoding="async">
</figure>
<h2 id="output-types">Output types</h2>
<div class="output-type" id="contact-sheets">
<div>
<h3>Contact sheets</h3>
<p>A grid of timestamped frames sampled evenly across the video's duration. Best for archival indexes, dailies review, or quick "what's in this file" catalogs.</p>
<p><strong>Options:</strong> rows × columns, format (PNG / JPEG), JPEG quality, width, optional header with filename + metadata, timestamp overlay, font.</p>
</div>
<div class="output-type-media">
<img class="optional-screenshot" src="assets/screenshots/output-contact-sheet.webp" alt="Sample contact sheet output" width="1200" height="1443" loading="lazy" decoding="async">
</div>
</div>
<div class="output-type" id="screenshots">
<div>
<h3>Screenshots</h3>
<p>Individual frames extracted at evenly-spaced timestamps, configurable count. Each file named after the source video with an index suffix.</p>
<p><strong>Options:</strong> count, format (PNG / JPEG), JPEG quality, suffix.</p>
</div>
<div class="output-type-media">
<img class="optional-screenshot" src="assets/screenshots/output-screenshots.webp" alt="Sample screenshot grid output" width="1600" height="450" loading="lazy" decoding="async">
</div>
</div>
<div class="output-type" id="animated-previews">
<div>
<h3>Animated previews</h3>
<p>Two flavors of motion preview, sharing the same underlying clip extractor:</p>
<ul>
<li><strong>Reel</strong> — short clips stitched end-to-end into a single WebP, WebM, or GIF. Motion preview without full playback.</li>
<li><strong>Animated grid</strong> — a contact-sheet grid where every cell loops a short motion clip. All clips visible at once. WebP only.</li>
</ul>
<p><strong>Options:</strong> clip count, clip length, framerate, output dimensions, quality, format (WebP / WebM / GIF for reel; WebP for grid).</p>
</div>
<div class="output-type-media">
<img class="optional-screenshot" src="assets/screenshots/output-animated-reel.webp" alt="Sample animated preview" width="480" height="270" loading="lazy" decoding="async">
</div>
</div>
<h2 id="settings">Settings</h2>
<p>Click the gear icon in the header to configure defaults. Settings persist across launches.</p>
<figure class="showcase" style="margin: 2em 0;">
<img class="optional-screenshot" src="assets/screenshots/settings.webp" alt="Mosaic settings panel" width="1600" height="1238" loading="lazy" decoding="async">
</figure>
<p>Each output type has its own section with its own knobs — quality, dimensions, suffix for generated filenames, font choice for overlays, header fields, and format-specific encoding parameters. Theme follows your system preference automatically.</p>
<h2 id="mediainfo">MediaInfo viewer</h2>
<p>Every queue row has a small info icon next to the filename. Click it to open a modal showing the raw <a href="https://mediaarea.net/en/MediaInfo"><code>mediainfo</code></a> output for that file — video codec, bitrate, HDR profile, audio tracks, container metadata, everything MediaInfo knows.</p>
<p>There's a copy-to-clipboard button for pasting into issue reports, forum threads, or metadata logs.</p>
<p>MediaInfo is a required prerequisite — if it's missing at startup, Mosaic shows the same "required tools not found" state it does for ffmpeg. See <a href="#requirements">Requirements</a> for install commands.</p>
<h2 id="auto-update">Auto-update</h2>
<p>Every time you launch Mosaic (v0.1.2 or later), it silently checks GitHub for a newer release. If one exists, a native dialog appears:</p>
<div class="callout">
<strong>Mosaic 0.1.3 is available</strong> — Download and install? The app will restart. <strong>[Install] [Later]</strong>
</div>
<p>Click <strong>Install</strong> and Mosaic downloads the new version, verifies its cryptographic signature against the embedded public key, installs, and relaunches. No manual download, no re-install.</p>
<p>Update checks never send anything about your videos — only an unauthenticated HTTP request for the release metadata.</p>
<p><strong>v0.1.1 and earlier:</strong> those versions predate the auto-updater — you'll need to download v0.1.2+ manually once. From then on, updates flow automatically.</p>
<h2 id="cli">Command-line (CLI)</h2>
<p>Mosaic ships a <code>mosaic-cli</code> binary for scripting, CI, and headless servers. Install with one line on any platform:</p>
<pre><code># macOS / Linux
curl -LsSf https://mosaicvideo.github.io/install.sh | sh
# Windows (PowerShell)
irm https://mosaicvideo.github.io/install.ps1 | iex</code></pre>
<p>Full subcommand reference, config file format, shell completions, and troubleshooting live on the <a href="cli.html">CLI page</a>.</p>
<h2 id="faq">FAQ</h2>
<div class="faq">
<details class="faq-item">
<summary data-num="01">Do I really need ffmpeg separately? Why isn't it bundled?</summary>
<div class="faq-body">
<p>Bundling ffmpeg triples the installer size and locks you into whatever build options we picked. We recommend <code>ffmpeg-full</code> (which ships with libfreetype + libzimg for drawtext and HDR tonemapping). Keeping ffmpeg external lets you upgrade it independently.</p>
<p>The app checks for <code>ffmpeg</code> and <code>ffprobe</code> on your <code>PATH</code> at startup. If either is missing, you'll see install instructions and a <em>Retry</em> button.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="02">macOS says "Apple could not verify Mosaic is free of malware"</summary>
<div class="faq-body">
<p>From v0.1.2 onward, macOS builds are Developer-ID signed and notarized. You should <strong>not</strong> see this warning. If you do on a very recent macOS:</p>
<ul>
<li>Make sure you're on v0.1.2 or later (check the window title — it shows the version).</li>
<li>Right-click the app once → <strong>Open</strong>. Subsequent launches are fine.</li>
<li>If the issue persists, <a href="https://github.com/mosaicvideo/mosaic/issues/new">file an issue</a> — this shouldn't happen.</li>
</ul>
</div>
</details>
<details class="faq-item">
<summary data-num="03">Windows SmartScreen blocks the installer</summary>
<div class="faq-body">
<p>Windows builds aren't code-signed yet (EV certificates are expensive). SmartScreen warns until enough users download and confirm the file is safe.</p>
<p>Click <strong>More info</strong> → <strong>Run anyway</strong>. Source is open on <a href="https://github.com/mosaicvideo/mosaic">GitHub</a>, releases are built by GitHub Actions from tagged commits — you can verify the build chain.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="04">Where are my output files saved?</summary>
<div class="faq-body">
<p>Two choices in the output row at the bottom of the app:</p>
<ul>
<li><strong>Next to source</strong> — outputs land in the same folder as each video, with a suffix (e.g. <code>myvideo_sheet.jpg</code>). Best for processing a single folder in place.</li>
<li><strong>Custom folder</strong> — all outputs go into one folder you pick. Best for batch runs across multiple source folders.</li>
</ul>
<p>Filenames follow <code>{sourcename}{suffix}.{ext}</code>. Collisions get a <code>(1)</code>, <code>(2)</code> numeric suffix so nothing is overwritten.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="05">How does the auto-update work? When is it checked?</summary>
<div class="faq-body">
<p>Once on every app launch, from v0.1.2 onward. Mosaic asks GitHub whether a newer release exists; if one does, a native dialog offers to install it. Accepting downloads the new version, verifies its cryptographic signature against a public key embedded in the app, installs, and relaunches — no manual download or re-install.</p>
<p>Zero telemetry. The only request is an unauthenticated fetch of the public <code>latest.json</code> from this GitHub repo; nothing about your videos is ever sent. See <a href="#auto-update">Auto-update</a> for the full flow.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="06">Can I cancel a job mid-way?</summary>
<div class="faq-body">
<p>Yes. Click <strong>Cancel</strong> in the action bar. The currently-running ffmpeg process is killed; files already completed are kept, in-flight files are cleaned up.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="07">My HDR video produces weird colors — what version of ffmpeg do I need?</summary>
<div class="faq-body">
<p>HDR tonemapping (HDR10, HLG) requires ffmpeg built with <code>libzimg</code> (the <code>zscale</code> filter). Default Homebrew <code>ffmpeg</code> on macOS lacks it — install <code>ffmpeg-full</code> instead:</p>
<pre><code>brew install ffmpeg-full</code></pre>
<p>Mosaic prefers <code>ffmpeg-full</code> automatically when present. For Dolby Vision Profile 5, a built-in IPT-PQ-C2 → BT.709 color correction runs regardless of ffmpeg build — no zscale required.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="08">Do I need to install MediaInfo too?</summary>
<div class="faq-body">
<p>Yes. Mosaic uses MediaInfo both to build richer contact-sheet headers (HDR format, commercial audio codec name, channel layout, language) and to power the per-file metadata viewer. Mosaic checks for <code>mediainfo</code> on your <code>PATH</code> at startup and shows the same "required tools not found" message as it does for missing ffmpeg.</p>
<p>Installation is a one-liner per platform: <code>brew install mediainfo</code> on macOS, <code>winget install MediaArea.MediaInfo.CLI</code> on Windows, or <code>apt install mediainfo</code> on Debian and Ubuntu. See <a href="#requirements">Requirements</a> for the full list.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="09">Which video formats are supported?</summary>
<div class="faq-body">
<p>45 container types — anything ffmpeg can decode. This includes common formats (MP4, MKV, MOV, AVI, WebM, M4V), broadcast (MXF, R3D), transport streams (TS, M2TS), camcorder formats (DV, WTV), and legacy containers. If ffmpeg can probe it, Mosaic can process it.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="10">How big are the output files?</summary>
<div class="faq-body">
<p>Depends on output type and settings:</p>
<ul>
<li><strong>Contact sheets:</strong> 200 KB – 5 MB (JPEG 80–95% quality, 1920×wide).</li>
<li><strong>Screenshots:</strong> 50 KB – 2 MB each at full width.</li>
<li><strong>Animated previews (WebP):</strong> 500 KB – 10 MB for a few seconds of motion.</li>
<li><strong>Animated contact sheets:</strong> 1 – 20 MB depending on grid size and clip length.</li>
</ul>
<p>All dimensions and quality are configurable in settings.</p>
</div>
</details>
<details class="faq-item">
<summary data-num="11">Does Mosaic upload my videos anywhere?</summary>
<div class="faq-body">
<p>No. Everything happens locally via ffmpeg. The only network activity is the auto-update check — a single GET to GitHub's public releases API. No analytics, no telemetry, no cloud component, no account.</p>
</div>
</details>
</div>
</article>
</div>
</div>
</main>
<footer>
<div class="footer-inner">
<div class="footer-left">
<span class="version-badge" id="version-badge">latest</span>
<span>MIT</span>
</div>
<div class="footer-mark">mosaic</div>
<div class="footer-right">
<a href="https://github.com/mosaicvideo/mosaic">git</a>
<a href="https://github.com/mosaicvideo/mosaic/issues">issues</a>
<a href="https://github.com/mosaicvideo/mosaic/blob/main/CHANGELOG.md">log</a>
</div>
</div>
</footer>
<script src="assets/download.js" defer></script>
</body>
</html>