ancient-processor 4.1.0__tar.gz → 4.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (167) hide show
  1. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/CHANGELOG.md +24 -0
  2. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/PKG-INFO +1 -1
  3. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/PKG-INFO +1 -1
  4. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/scm_version.json +2 -2
  5. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/estimators.py +243 -38
  6. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/templates.py +9 -7
  7. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_estimators.py +387 -10
  8. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_templates.py +3 -0
  9. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.gitattributes +0 -0
  10. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.github/dependabot.yml +0 -0
  11. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.github/pull_request_template.md +0 -0
  12. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.github/workflows/ci.yml +0 -0
  13. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.github/workflows/pages.yml +0 -0
  14. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.github/workflows/release.yml +0 -0
  15. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/.gitignore +0 -0
  16. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/CONTRIBUTING.md +0 -0
  17. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/LICENSE +0 -0
  18. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/MANIFEST.in +0 -0
  19. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/README.md +0 -0
  20. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/THIRD_PARTY_NOTICES.md +0 -0
  21. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/docs/acceptance.md +0 -0
  22. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/docs/release-plan.md +0 -0
  23. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/docs/system-design.md +0 -0
  24. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/docs/ui-wizard.md +0 -0
  25. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/pyproject.toml +0 -0
  26. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/setup.cfg +0 -0
  27. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/setup.py +0 -0
  28. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/SOURCES.txt +0 -0
  29. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/dependency_links.txt +0 -0
  30. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/entry_points.txt +0 -0
  31. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/requires.txt +0 -0
  32. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/scm_file_list.json +0 -0
  33. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/ancient_processor.egg-info/top_level.txt +0 -0
  34. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/__init__.py +0 -0
  35. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/__main__.py +0 -0
  36. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/_core.pyi +0 -0
  37. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/_core.pyx +0 -0
  38. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/cli.py +0 -0
  39. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/diagnose.py +0 -0
  40. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/doctor.py +0 -0
  41. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/encoders.py +0 -0
  42. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/file_dialog.py +0 -0
  43. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/gemini.py +0 -0
  44. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/gpu_heat.py +0 -0
  45. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/jobs.py +0 -0
  46. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/look.py +0 -0
  47. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/models.py +0 -0
  48. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/plan.py +0 -0
  49. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/plans.py +0 -0
  50. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/preview.py +0 -0
  51. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/probe.py +0 -0
  52. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/progress.py +0 -0
  53. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/py.typed +0 -0
  54. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/qa.py +0 -0
  55. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/recipe.py +0 -0
  56. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/reframe.py +0 -0
  57. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/regions.py +0 -0
  58. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/render.py +0 -0
  59. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/review.py +0 -0
  60. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/segment_loop.py +0 -0
  61. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/segments.py +0 -0
  62. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/shot_plan.py +0 -0
  63. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/shots.py +0 -0
  64. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/span_sr.py +0 -0
  65. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/stability.py +0 -0
  66. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/treatments.py +0 -0
  67. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/upscale.py +0 -0
  68. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/validator.py +0 -0
  69. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/wizard.py +0 -0
  70. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/wizard_pages.py +0 -0
  71. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/src/super_processor/worker.py +0 -0
  72. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/conftest.py +0 -0
  73. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/loop_driver.py +0 -0
  74. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_api_key_store.py +0 -0
  75. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_audio_mux.py +0 -0
  76. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_cli.py +0 -0
  77. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_core.py +0 -0
  78. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_diagnose_plan.py +0 -0
  79. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_doctor.py +0 -0
  80. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_faults.py +0 -0
  81. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_frame_alignment.py +0 -0
  82. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gemini.py +0 -0
  83. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gemini_live.py +0 -0
  84. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gemini_video.py +0 -0
  85. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gpu_blend.py +0 -0
  86. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gpu_codec.py +0 -0
  87. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gpu_heat.py +0 -0
  88. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_gpu_strength.py +0 -0
  89. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_hwdecode.py +0 -0
  90. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_job_cli.py +0 -0
  91. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_jobs.py +0 -0
  92. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_kept_duration.py +0 -0
  93. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_look.py +0 -0
  94. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_packaging.py +0 -0
  95. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_pass_through.py +0 -0
  96. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_plan_cli.py +0 -0
  97. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_plan_io.py +0 -0
  98. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_plan_pick.py +0 -0
  99. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_plan_revise.py +0 -0
  100. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_plan_score.py +0 -0
  101. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_preview_encode.py +0 -0
  102. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_preview_window.py +0 -0
  103. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_probe.py +0 -0
  104. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_product_flow.py +0 -0
  105. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_progress.py +0 -0
  106. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_recipe.py +0 -0
  107. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_reframe.py +0 -0
  108. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_regions.py +0 -0
  109. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_render_argv.py +0 -0
  110. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_render_choose.py +0 -0
  111. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_review_server.py +0 -0
  112. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_apply.py +0 -0
  113. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_bounds.py +0 -0
  114. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_cli.py +0 -0
  115. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_ffmpeg.py +0 -0
  116. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_groups.py +0 -0
  117. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_labels.py +0 -0
  118. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_loop.py +0 -0
  119. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_loop_wizard.py +0 -0
  120. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_merge.py +0 -0
  121. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_notes.py +0 -0
  122. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_review.py +0 -0
  123. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_sample.py +0 -0
  124. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_samples_io.py +0 -0
  125. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_score.py +0 -0
  126. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_segment_split.py +0 -0
  127. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_sentence.py +0 -0
  128. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_shot_plan.py +0 -0
  129. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_shots.py +0 -0
  130. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_span_gpu.py +0 -0
  131. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_stability.py +0 -0
  132. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_timing_safety.py +0 -0
  133. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_treatments.py +0 -0
  134. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_upscale.py +0 -0
  135. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_validator.py +0 -0
  136. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_vmaf.py +0 -0
  137. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard.py +0 -0
  138. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_api.py +0 -0
  139. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_cli.py +0 -0
  140. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_edges.py +0 -0
  141. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_flow_steps.py +0 -0
  142. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_full_flow.py +0 -0
  143. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_hardening.py +0 -0
  144. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_media.py +0 -0
  145. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_media_routes.py +0 -0
  146. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_navigation.py +0 -0
  147. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_note_scale.py +0 -0
  148. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_pages.py +0 -0
  149. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_render_steps.py +0 -0
  150. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_wizard_safety.py +0 -0
  151. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/tests/test_worker.py +0 -0
  152. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/uv.lock +0 -0
  153. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/index.html +0 -0
  154. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/package-lock.json +0 -0
  155. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/package.json +0 -0
  156. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/scripts/a11y.mjs +0 -0
  157. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/App.tsx +0 -0
  158. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/LiveWizard.tsx +0 -0
  159. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/StaticShell.tsx +0 -0
  160. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/api.ts +0 -0
  161. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/main.tsx +0 -0
  162. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/styles.css +0 -0
  163. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/src/vite-env.d.ts +0 -0
  164. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/tests/api.test.mjs +0 -0
  165. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/tests/proxy.test.mjs +0 -0
  166. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/tsconfig.json +0 -0
  167. {ancient_processor-4.1.0 → ancient_processor-4.1.1}/web/vite.config.ts +0 -0
@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [4.1.1] - 2026-11-17
11
+
12
+ ### Fixed
13
+
14
+ - `diagnose` suggested brightening and adding contrast to nearly every dark
15
+ video, turning black backgrounds milky grey and burning out whites. It
16
+ pushed each picture's average toward mid grey and counted every black
17
+ pixel as clipped: a 1990s documentary's interview lit against black got
18
+ contrast 2.0 and +0.44 brightness. It now judges 9 frames spread over
19
+ the whole video and corrects only a faded picture: one with no true
20
+ black in any frame but a title card or two (black at level 20 or above),
21
+ measured inside any letterbox or pillarbox bars. Its black goes back to
22
+ video black, and its whites are stretched as far as a fade of that lift
23
+ explains (at most 2 times), never dimmer than they were and with no
24
+ sampled frame pushed into clipping. A picture that reaches true black is
25
+ left alone however dark or dim it is, since a dim transfer cannot be told
26
+ from a film shot dark on purpose. Full-range video (yuvj, MJPEG) gets its
27
+ own brightness, levels are corrected before white balance, and a video
28
+ of unknown length is not judged from its first second. Four archive
29
+ films are now gently corrected, every modern clip and the documentary
30
+ are left alone, and faded copies come back close to their originals.
31
+ Still missed: a faded film whose samples land mostly on black title
32
+ cards. Diagnosing takes about 0.1 s longer at SD and 0.6 s at 1080p.
33
+
10
34
  ## [4.1.0] - 2026-11-16
11
35
 
12
36
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ancient-processor
3
- Version: 4.1.0
3
+ Version: 4.1.1
4
4
  Summary: Local-first AI-assisted video processing
5
5
  Author: Super Processor contributors
6
6
  License-Expression: MIT
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ancient-processor
3
- Version: 4.1.0
3
+ Version: 4.1.1
4
4
  Summary: Local-first AI-assisted video processing
5
5
  Author: Super Processor contributors
6
6
  License-Expression: MIT
@@ -1,7 +1,7 @@
1
1
  {
2
- "tag": "4.1.0",
2
+ "tag": "4.1.1",
3
3
  "distance": 0,
4
- "node": "g1d79d221eac760a96f3de4163a58417ee2762043",
4
+ "node": "ga78ee51e37c864a1d7d94c8eedda16152d6b9538",
5
5
  "dirty": false,
6
6
  "branch": "HEAD",
7
7
  "node_date": "2026-11-17"
@@ -5,12 +5,12 @@ from __future__ import annotations
5
5
  import json
6
6
  import math
7
7
  import subprocess
8
- from array import array
8
+ from concurrent.futures import ThreadPoolExecutor
9
9
  from dataclasses import asdict, dataclass, field
10
10
  from pathlib import Path
11
11
  from typing import Any
12
12
 
13
- from . import histogram_u8, mean_luma, percentile_u8, sad_u8
13
+ from . import mean_luma, percentile_u8, sad_u8
14
14
  from .doctor import check_ffmpeg_capability, which
15
15
  from .encoders import HARDWARE_DECODERS, decoder_input_args
16
16
  from .probe import MediaFacts, parse_frame_rate
@@ -360,51 +360,233 @@ def extract_rgb_means(
360
360
  return r_total / scale, g_total / scale, b_total / scale
361
361
 
362
362
 
363
- def _estimate_contrast(frames: list[bytes]) -> tuple[OpSuggestion, dict[str, float]]:
364
- p05_vals: list[float] = []
365
- p95_vals: list[float] = []
366
- means: list[float] = []
367
- clip_lows: list[float] = []
368
- clip_highs: list[float] = []
369
- hist = array("Q", [0]) * 256
363
+ # Contrast is judged on frames spread over the whole video, so that one
364
+ # dark or bright scene does not decide it for the rest.
365
+ CONTRAST_SAMPLES = 9
366
+ # A frame's black and white points: its 1st and 99th percentile, so a few
367
+ # stray pixels (a logo, a scratch, a speck of dust) do not count.
368
+ _BLACK_PCT = 1.0
369
+ _WHITE_PCT = 99.0
370
+ # A frame spanning fewer levels than this is a fade or a blank card.
371
+ _BLANK_SPAN = 24.0
372
+ # Rows and columns at the edge no brighter than this in every sampled frame
373
+ # are letterbox or pillarbox bars, not picture. The scaled picture's own
374
+ # edge bleeds into the bar, so 2 more pixels are dropped there.
375
+ _BAR_LEVEL = 12
376
+ _BAR_BLEED = 2
377
+ # Where a faded picture's black and white are put back (8-bit grey, where
378
+ # video black is 0 and video white 255). No sampled frame's white is
379
+ # pushed past _CLIP_WHITE.
380
+ _TARGET_BLACK = 4.0
381
+ _TARGET_WHITE = 240.0
382
+ _CLIP_WHITE = 250.0
383
+ # Black at or above this level in nearly every frame is a faded print or a
384
+ # lifted transfer. Clean and well-kept video measures 0-18 here.
385
+ _LIFTED_BLACK = 20.0
386
+ # Fading pulls the whole picture toward a grey: faded = a*picture +
387
+ # (1-a)*grey, which lifts black by (1-a)*grey and squeezes the range by a.
388
+ # Whites are stretched only as far as the black's lift explains, so a
389
+ # barely lifted black does not bring a large boost to dim whites, which may
390
+ # be the scene's own.
391
+ _FADE_GREY = 128.0
392
+ _MAX_STRETCH = 2.0
393
+ # FFmpeg's eq works on the stored levels. On limited-range video (black 16,
394
+ # white 235) a grey frame stretches those over 0-255; on full-range video
395
+ # (yuvj, MJPEG, some phones) grey is the stored level itself. Its contrast
396
+ # turns about level 127.5 + 0.5/(c-1) and its brightness adds 255.5 levels
397
+ # per 1.0.
398
+ _GRAY_PER_LEVEL = 255.0 / 219.0
399
+
400
+
401
+ def contrast_sample_times(
402
+ duration_s: float, count: int = CONTRAST_SAMPLES
403
+ ) -> list[float]:
404
+ """Evenly spread times to judge contrast at, clear of both ends: a seek
405
+ into the last frame's own time finds no frame to decode."""
406
+ duration = max(0.5, duration_s)
407
+ last = max(0.0, duration - 0.25)
408
+ return [min(last, duration * (index + 0.5) / count) for index in range(count)]
409
+
410
+
411
+ def _eq_brightness(
412
+ contrast: float, black: float, target: float, *, full_range: bool = False
413
+ ) -> float:
414
+ """The eq brightness that puts grey level ``black`` at ``target`` after
415
+ eq scales it by ``contrast``."""
416
+ if full_range:
417
+ return (target - contrast * (black - 128.0) - 127.5) / 255.5
418
+ level = (target - contrast * black) / _GRAY_PER_LEVEL
419
+ return (level - 111.5 + 112.0 * contrast) / 255.5
420
+
421
+
422
+ def is_full_range(facts: MediaFacts) -> bool:
423
+ """Whether the video stores full-range levels (0-255, not 16-235)."""
424
+ video = facts.primary_video()
425
+ if video is None:
426
+ return False
427
+ return video.color_range == "pc" or (video.pix_fmt or "").startswith("yuvj")
428
+
429
+
430
+ def media_duration(facts: MediaFacts) -> float | None:
431
+ """The video's length: the container's, else the video stream's, else
432
+ its frame count over its frame rate. None when nothing says."""
433
+ if facts.duration_s:
434
+ return facts.duration_s
435
+ video = facts.primary_video()
436
+ if video is None:
437
+ return None
438
+ if video.duration_s:
439
+ return video.duration_s
440
+ rate = parse_frame_rate(video.avg_frame_rate) or parse_frame_rate(
441
+ video.r_frame_rate
442
+ )
443
+ if video.nb_frames and rate:
444
+ return video.nb_frames / rate
445
+ return None
370
446
 
447
+
448
+ def _centred(near: int, far: int) -> bool:
449
+ """Whether bars of ``near`` and ``far`` pixels are a matched pair."""
450
+ return near > 0 and far > 0 and abs(near - far) <= _BAR_BLEED
451
+
452
+
453
+ def _picture_area(frames: list[bytes], width: int) -> tuple[int, int, int, int] | None:
454
+ """The rows and columns (top, bottom, left, right, inclusive) inside any
455
+ letterbox or pillarbox bars, or None when there are none."""
456
+ height = len(frames[0]) // width if frames and width else 0
457
+ if height < 4 or width < 4:
458
+ return None
459
+ row_max = [0] * height
460
+ col_max = [0] * width
371
461
  for frame in frames:
372
- histogram_u8(frame, memoryview(hist))
373
- total = float(sum(hist))
374
- p05_vals.append(percentile_u8(frame, 5.0))
375
- p95_vals.append(percentile_u8(frame, 95.0))
462
+ for y in range(height):
463
+ row_max[y] = max(row_max[y], max(frame[y * width : (y + 1) * width]))
464
+ for x in range(width):
465
+ col_max[x] = max(col_max[x], max(frame[x : height * width : width]))
466
+ rows = [y for y, level in enumerate(row_max) if level > _BAR_LEVEL]
467
+ cols = [x for x, level in enumerate(col_max) if level > _BAR_LEVEL]
468
+ if not rows or not cols:
469
+ return None
470
+ top, bottom, left, right = rows[0], rows[-1], cols[0], cols[-1]
471
+ # Bars are centred: a dark band along one edge only is part of the
472
+ # picture (a night sky, a shadowed floor), and so is its true black.
473
+ if not _centred(top, height - 1 - bottom):
474
+ top, bottom = 0, height - 1
475
+ if not _centred(left, width - 1 - right):
476
+ left, right = 0, width - 1
477
+ if (top, bottom, left, right) == (0, height - 1, 0, width - 1):
478
+ return None
479
+ top += _BAR_BLEED if top else 0
480
+ bottom -= _BAR_BLEED if bottom < height - 1 else 0
481
+ left += _BAR_BLEED if left else 0
482
+ right -= _BAR_BLEED if right < width - 1 else 0
483
+ # Bars that leave less than a quarter of either side are not bars.
484
+ if bottom - top + 1 < height // 4 or right - left + 1 < width // 4:
485
+ return None
486
+ return top, bottom, left, right
487
+
488
+
489
+ def _no_contrast(
490
+ reason: str, metrics: dict[str, float]
491
+ ) -> tuple[OpSuggestion, dict[str, float]]:
492
+ return (
493
+ OpSuggestion(
494
+ enabled=False,
495
+ confidence=0.0,
496
+ params={"contrast": 1.0, "brightness": 0.0, "gamma": 1.0},
497
+ reason=reason,
498
+ ),
499
+ metrics,
500
+ )
501
+
502
+
503
+ def _estimate_contrast(
504
+ frames: list[bytes], width: int = 160, *, full_range: bool = False
505
+ ) -> tuple[OpSuggestion, dict[str, float]]:
506
+ """Restore the black of a faded picture, and leave every other alone.
507
+
508
+ How dark or bright a picture is belongs to its scene: a night shot, an
509
+ interview lit against black, a snowfield. A fault in the print or the
510
+ transfer instead shows in every frame, the dark ones too: a faded print
511
+ has no true black anywhere. So black is the second darkest frame's black
512
+ point, and white the second brightest frame's white point, which a
513
+ single title card or flash cannot move. Letterbox and pillarbox bars
514
+ are left out first: they are black whatever the print.
515
+
516
+ The black goes back to video black. The white is stretched only as far
517
+ as the black's lift explains, never ends up dimmer than it was, and no
518
+ sampled frame is pushed into clipping: from the picture alone, a dim
519
+ transfer cannot be told from a film shot dark on purpose.
520
+ """
521
+ area = _picture_area(frames, width)
522
+ if area is not None:
523
+ top, bottom, left, right = area
524
+ frames = [
525
+ b"".join(
526
+ frame[y * width + left : y * width + right + 1]
527
+ for y in range(top, bottom + 1)
528
+ )
529
+ for frame in frames
530
+ ]
531
+ blacks: list[float] = []
532
+ whites: list[float] = []
533
+ means: list[float] = []
534
+ for frame in frames:
535
+ low = percentile_u8(frame, _BLACK_PCT)
536
+ high = percentile_u8(frame, _WHITE_PCT)
376
537
  means.append(mean_luma(frame))
377
- clip_lows.append(hist[0] / total)
378
- clip_highs.append(hist[255] / total)
379
-
380
- p05 = sum(p05_vals) / len(p05_vals)
381
- p95 = sum(p95_vals) / len(p95_vals)
382
- mean = sum(means) / len(means)
383
- span = max(1.0, p95 - p05)
384
- # Map compressed spans toward a mild contrast boost.
385
- contrast = max(0.5, min(2.0, 180.0 / span))
386
- brightness = max(-0.5, min(0.5, (128.0 - mean) / 255.0))
387
- clip = (sum(clip_lows) + sum(clip_highs)) / len(frames)
388
- enabled = contrast > 1.08 or abs(brightness) > 0.04 or clip > 0.02
389
- confidence = min(
390
- 1.0, abs(contrast - 1.0) * 2.0 + abs(brightness) * 2.0 + clip * 5.0
538
+ if high - low >= _BLANK_SPAN:
539
+ blacks.append(low)
540
+ whites.append(high)
541
+ mean = sum(means) / len(means) if means else 0.0
542
+ metrics = {"luma_mean": mean}
543
+ if len(blacks) < 2:
544
+ return _no_contrast("too few frames with a picture to judge contrast", metrics)
545
+
546
+ black = sorted(blacks)[1]
547
+ white = sorted(whites)[-2]
548
+ metrics.update({"luma_black": black, "luma_white": white})
549
+ lifted = black >= _LIFTED_BLACK
550
+ contrast = 1.0
551
+ brightness = 0.0
552
+ if lifted:
553
+ span = max(1.0, white - black)
554
+ full = (_TARGET_WHITE - _TARGET_BLACK) / span
555
+ lift = min(_FADE_GREY - 1.0, black - _TARGET_BLACK)
556
+ explained = _FADE_GREY / (_FADE_GREY - lift)
557
+ contrast = min(full, explained)
558
+ # Pulling black down never leaves the whites dimmer than they were.
559
+ contrast = max(contrast, (white - _TARGET_BLACK) / span)
560
+ brightest = max(1.0, max(whites) - black)
561
+ contrast = min(contrast, (_CLIP_WHITE - _TARGET_BLACK) / brightest)
562
+ contrast = max(1.0, min(_MAX_STRETCH, contrast))
563
+ brightness = max(
564
+ -0.5,
565
+ min(
566
+ 0.5,
567
+ _eq_brightness(contrast, black, _TARGET_BLACK, full_range=full_range),
568
+ ),
569
+ )
570
+ confidence = (
571
+ min(1.0, (black - _LIFTED_BLACK + 10.0) / 30.0 + (contrast - 1.0))
572
+ if lifted
573
+ else 0.0
391
574
  )
575
+ state = "lifted" if lifted else "true black"
576
+ bars = " inside bars" if area is not None else ""
392
577
  suggestion = OpSuggestion(
393
- enabled=enabled,
578
+ enabled=lifted,
394
579
  confidence=confidence,
395
580
  params={
396
- "contrast": round(contrast if enabled else 1.0, 3),
397
- "brightness": round(brightness if enabled else 0.0, 3),
581
+ "contrast": round(contrast, 3),
582
+ "brightness": round(brightness, 3),
398
583
  "gamma": 1.0,
399
584
  },
400
- reason=(f"luma p05={p05:.1f} p95={p95:.1f} mean={mean:.1f} clip={clip:.3f}"),
585
+ reason=(
586
+ f"black={black:.0f} ({state}) white={white:.0f} "
587
+ f"over {len(blacks)} frames{bars}, mean={mean:.0f}"
588
+ ),
401
589
  )
402
- metrics = {
403
- "luma_p05": p05,
404
- "luma_p95": p95,
405
- "luma_mean": mean,
406
- "clip_fraction": clip,
407
- }
408
590
  return suggestion, metrics
409
591
 
410
592
 
@@ -737,7 +919,30 @@ def estimate_look(
737
919
  extract_rgb_means(source, at_s=window.start_s, ffmpeg_bin=ffmpeg_bin)
738
920
  )
739
921
 
740
- contrast, contrast_metrics = _estimate_contrast(gray_frames)
922
+ # Each frame is its own ffmpeg process, so they decode side by side:
923
+ # nine seeks into 1080p video take 0.6 s instead of 1.6 s.
924
+ # A frame that will not decode is left out, as a blank one would be.
925
+ def contrast_frame(at_s: float) -> bytes | None:
926
+ try:
927
+ return extract_gray_frame(source, at_s=at_s, ffmpeg_bin=ffmpeg_bin)
928
+ except EstimatorError:
929
+ return None
930
+
931
+ length = media_duration(facts)
932
+ if length is None:
933
+ contrast, contrast_metrics = _no_contrast(
934
+ "duration unknown: cannot spread contrast samples", {}
935
+ )
936
+ else:
937
+ with ThreadPoolExecutor(max_workers=4) as pool:
938
+ contrast_frames = [
939
+ frame
940
+ for frame in pool.map(contrast_frame, contrast_sample_times(length))
941
+ if frame is not None
942
+ ]
943
+ contrast, contrast_metrics = _estimate_contrast(
944
+ contrast_frames, full_range=is_full_range(facts)
945
+ )
741
946
  white_balance, wb_metrics = _estimate_white_balance(rgb_means)
742
947
  if side is None:
743
948
  denoise, denoise_metrics = _estimate_denoise(gray_frames)
@@ -99,6 +99,15 @@ def _op_map(recipe: Recipe) -> dict[OpName, RecipeOp]:
99
99
  def _look_filters(ops: dict[OpName, RecipeOp]) -> list[str]:
100
100
  filters: list[str] = []
101
101
 
102
+ # Levels first: the contrast estimate measured black and white on the
103
+ # source, and colortemperature moves them.
104
+ contrast = ops.get(OpName.CONTRAST)
105
+ if contrast is not None:
106
+ c = float(contrast.params.get("contrast", 1.0))
107
+ b = float(contrast.params.get("brightness", 0.0))
108
+ g = float(contrast.params.get("gamma", 1.0))
109
+ filters.append(f"eq=contrast={c:g}:brightness={b:g}:gamma={g:g}")
110
+
102
111
  wb = ops.get(OpName.WHITE_BALANCE)
103
112
  if wb is not None:
104
113
  temperature = float(wb.params.get("temperature", 6500.0))
@@ -109,13 +118,6 @@ def _look_filters(ops: dict[OpName, RecipeOp]) -> list[str]:
109
118
  amount = max(-1.0, min(1.0, tint / 100.0)) * 0.25
110
119
  filters.append(f"colorbalance=gm={amount:g}")
111
120
 
112
- contrast = ops.get(OpName.CONTRAST)
113
- if contrast is not None:
114
- c = float(contrast.params.get("contrast", 1.0))
115
- b = float(contrast.params.get("brightness", 0.0))
116
- g = float(contrast.params.get("gamma", 1.0))
117
- filters.append(f"eq=contrast={c:g}:brightness={b:g}:gamma={g:g}")
118
-
119
121
  denoise = ops.get(OpName.DENOISE)
120
122
  if denoise is not None:
121
123
  strength = float(denoise.params.get("strength", 0.0))