stevenlearns commited on
Commit
7c8fbd2
·
verified ·
1 Parent(s): 2d10b43

Publish videoclean OpenCV tool source

Browse files
Files changed (43) hide show
  1. .gitignore +6 -0
  2. LICENSE +674 -0
  3. LICENSE-APACHE-2.0 +202 -0
  4. Makefile +8 -0
  5. NOTICE +10 -0
  6. PROVENANCE.md +11 -0
  7. README.md +52 -0
  8. pyproject.toml +28 -0
  9. src/videoclean/__init__.py +9 -0
  10. src/videoclean/__pycache__/__init__.cpython-314.pyc +0 -0
  11. src/videoclean/__pycache__/api.cpython-314.pyc +0 -0
  12. src/videoclean/__pycache__/cli.cpython-314.pyc +0 -0
  13. src/videoclean/__pycache__/detect.cpython-314.pyc +0 -0
  14. src/videoclean/__pycache__/engine.cpython-314.pyc +0 -0
  15. src/videoclean/__pycache__/errors.cpython-314.pyc +0 -0
  16. src/videoclean/__pycache__/ocr.cpython-314.pyc +0 -0
  17. src/videoclean/__pycache__/plan.cpython-314.pyc +0 -0
  18. src/videoclean/__pycache__/weights.cpython-314.pyc +0 -0
  19. src/videoclean/api.py +103 -0
  20. src/videoclean/cli.py +134 -0
  21. src/videoclean/detect.py +1538 -0
  22. src/videoclean/engine.py +362 -0
  23. src/videoclean/errors.py +52 -0
  24. src/videoclean/inpainters/__init__.py +8 -0
  25. src/videoclean/inpainters/__pycache__/__init__.cpython-314.pyc +0 -0
  26. src/videoclean/inpainters/__pycache__/base.cpython-314.pyc +0 -0
  27. src/videoclean/inpainters/__pycache__/opencv.cpython-314.pyc +0 -0
  28. src/videoclean/inpainters/__pycache__/registry.cpython-314.pyc +0 -0
  29. src/videoclean/inpainters/base.py +100 -0
  30. src/videoclean/inpainters/opencv.py +134 -0
  31. src/videoclean/inpainters/registry.py +44 -0
  32. src/videoclean/ocr.py +77 -0
  33. src/videoclean/plan.py +791 -0
  34. src/videoclean/tasks/__init__.py +3 -0
  35. src/videoclean/tasks/__pycache__/__init__.cpython-314.pyc +0 -0
  36. src/videoclean/tasks/__pycache__/base.cpython-314.pyc +0 -0
  37. src/videoclean/tasks/__pycache__/detext.cpython-314.pyc +0 -0
  38. src/videoclean/tasks/base.py +46 -0
  39. src/videoclean/tasks/detext.py +38 -0
  40. src/videoclean/weights.py +52 -0
  41. tests/__pycache__/test_opencv_inpainter.cpython-314-pytest-9.1.1.pyc +0 -0
  42. tests/test_opencv_inpainter.py +62 -0
  43. vpipe +64 -0
.gitignore ADDED
@@ -0,0 +1,6 @@
 
 
 
 
 
 
 
1
+ .venv/
2
+ __pycache__/
3
+ .pytest_cache/
4
+ .ruff_cache/
5
+ dist/
6
+ *.egg-info/
LICENSE ADDED
@@ -0,0 +1,674 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ GNU GENERAL PUBLIC LICENSE
2
+ Version 3, 29 June 2007
3
+
4
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
5
+ Everyone is permitted to copy and distribute verbatim copies
6
+ of this license document, but changing it is not allowed.
7
+
8
+ Preamble
9
+
10
+ The GNU General Public License is a free, copyleft license for
11
+ software and other kinds of works.
12
+
13
+ The licenses for most software and other practical works are designed
14
+ to take away your freedom to share and change the works. By contrast,
15
+ the GNU General Public License is intended to guarantee your freedom to
16
+ share and change all versions of a program--to make sure it remains free
17
+ software for all its users. We, the Free Software Foundation, use the
18
+ GNU General Public License for most of our software; it applies also to
19
+ any other work released this way by its authors. You can apply it to
20
+ your programs, too.
21
+
22
+ When we speak of free software, we are referring to freedom, not
23
+ price. Our General Public Licenses are designed to make sure that you
24
+ have the freedom to distribute copies of free software (and charge for
25
+ them if you wish), that you receive source code or can get it if you
26
+ want it, that you can change the software or use pieces of it in new
27
+ free programs, and that you know you can do these things.
28
+
29
+ To protect your rights, we need to prevent others from denying you
30
+ these rights or asking you to surrender the rights. Therefore, you have
31
+ certain responsibilities if you distribute copies of the software, or if
32
+ you modify it: responsibilities to respect the freedom of others.
33
+
34
+ For example, if you distribute copies of such a program, whether
35
+ gratis or for a fee, you must pass on to the recipients the same
36
+ freedoms that you received. You must make sure that they, too, receive
37
+ or can get the source code. And you must show them these terms so they
38
+ know their rights.
39
+
40
+ Developers that use the GNU GPL protect your rights with two steps:
41
+ (1) assert copyright on the software, and (2) offer you this License
42
+ giving you legal permission to copy, distribute and/or modify it.
43
+
44
+ For the developers' and authors' protection, the GPL clearly explains
45
+ that there is no warranty for this free software. For both users' and
46
+ authors' sake, the GPL requires that modified versions be marked as
47
+ changed, so that their problems will not be attributed erroneously to
48
+ authors of previous versions.
49
+
50
+ Some devices are designed to deny users access to install or run
51
+ modified versions of the software inside them, although the manufacturer
52
+ can do so. This is fundamentally incompatible with the aim of
53
+ protecting users' freedom to change the software. The systematic
54
+ pattern of such abuse occurs in the area of products for individuals to
55
+ use, which is precisely where it is most unacceptable. Therefore, we
56
+ have designed this version of the GPL to prohibit the practice for those
57
+ products. If such problems arise substantially in other domains, we
58
+ stand ready to extend this provision to those domains in future versions
59
+ of the GPL, as needed to protect the freedom of users.
60
+
61
+ Finally, every program is threatened constantly by software patents.
62
+ States should not allow patents to restrict development and use of
63
+ software on general-purpose computers, but in those that do, we wish to
64
+ avoid the special danger that patents applied to a free program could
65
+ make it effectively proprietary. To prevent this, the GPL assures that
66
+ patents cannot be used to render the program non-free.
67
+
68
+ The precise terms and conditions for copying, distribution and
69
+ modification follow.
70
+
71
+ TERMS AND CONDITIONS
72
+
73
+ 0. Definitions.
74
+
75
+ "This License" refers to version 3 of the GNU General Public License.
76
+
77
+ "Copyright" also means copyright-like laws that apply to other kinds of
78
+ works, such as semiconductor masks.
79
+
80
+ "The Program" refers to any copyrightable work licensed under this
81
+ License. Each licensee is addressed as "you". "Licensees" and
82
+ "recipients" may be individuals or organizations.
83
+
84
+ To "modify" a work means to copy from or adapt all or part of the work
85
+ in a fashion requiring copyright permission, other than the making of an
86
+ exact copy. The resulting work is called a "modified version" of the
87
+ earlier work or a work "based on" the earlier work.
88
+
89
+ A "covered work" means either the unmodified Program or a work based
90
+ on the Program.
91
+
92
+ To "propagate" a work means to do anything with it that, without
93
+ permission, would make you directly or secondarily liable for
94
+ infringement under applicable copyright law, except executing it on a
95
+ computer or modifying a private copy. Propagation includes copying,
96
+ distribution (with or without modification), making available to the
97
+ public, and in some countries other activities as well.
98
+
99
+ To "convey" a work means any kind of propagation that enables other
100
+ parties to make or receive copies. Mere interaction with a user through
101
+ a computer network, with no transfer of a copy, is not conveying.
102
+
103
+ An interactive user interface displays "Appropriate Legal Notices"
104
+ to the extent that it includes a convenient and prominently visible
105
+ feature that (1) displays an appropriate copyright notice, and (2)
106
+ tells the user that there is no warranty for the work (except to the
107
+ extent that warranties are provided), that licensees may convey the
108
+ work under this License, and how to view a copy of this License. If
109
+ the interface presents a list of user commands or options, such as a
110
+ menu, a prominent item in the list meets this criterion.
111
+
112
+ 1. Source Code.
113
+
114
+ The "source code" for a work means the preferred form of the work
115
+ for making modifications to it. "Object code" means any non-source
116
+ form of a work.
117
+
118
+ A "Standard Interface" means an interface that either is an official
119
+ standard defined by a recognized standards body, or, in the case of
120
+ interfaces specified for a particular programming language, one that
121
+ is widely used among developers working in that language.
122
+
123
+ The "System Libraries" of an executable work include anything, other
124
+ than the work as a whole, that (a) is included in the normal form of
125
+ packaging a Major Component, but which is not part of that Major
126
+ Component, and (b) serves only to enable use of the work with that
127
+ Major Component, or to implement a Standard Interface for which an
128
+ implementation is available to the public in source code form. A
129
+ "Major Component", in this context, means a major essential component
130
+ (kernel, window system, and so on) of the specific operating system
131
+ (if any) on which the executable work runs, or a compiler used to
132
+ produce the work, or an object code interpreter used to run it.
133
+
134
+ The "Corresponding Source" for a work in object code form means all
135
+ the source code needed to generate, install, and (for an executable
136
+ work) run the object code and to modify the work, including scripts to
137
+ control those activities. However, it does not include the work's
138
+ System Libraries, or general-purpose tools or generally available free
139
+ programs which are used unmodified in performing those activities but
140
+ which are not part of the work. For example, Corresponding Source
141
+ includes interface definition files associated with source files for
142
+ the work, and the source code for shared libraries and dynamically
143
+ linked subprograms that the work is specifically designed to require,
144
+ such as by intimate data communication or control flow between those
145
+ subprograms and other parts of the work.
146
+
147
+ The Corresponding Source need not include anything that users
148
+ can regenerate automatically from other parts of the Corresponding
149
+ Source.
150
+
151
+ The Corresponding Source for a work in source code form is that
152
+ same work.
153
+
154
+ 2. Basic Permissions.
155
+
156
+ All rights granted under this License are granted for the term of
157
+ copyright on the Program, and are irrevocable provided the stated
158
+ conditions are met. This License explicitly affirms your unlimited
159
+ permission to run the unmodified Program. The output from running a
160
+ covered work is covered by this License only if the output, given its
161
+ content, constitutes a covered work. This License acknowledges your
162
+ rights of fair use or other equivalent, as provided by copyright law.
163
+
164
+ You may make, run and propagate covered works that you do not
165
+ convey, without conditions so long as your license otherwise remains
166
+ in force. You may convey covered works to others for the sole purpose
167
+ of having them make modifications exclusively for you, or provide you
168
+ with facilities for running those works, provided that you comply with
169
+ the terms of this License in conveying all material for which you do
170
+ not control copyright. Those thus making or running the covered works
171
+ for you must do so exclusively on your behalf, under your direction
172
+ and control, on terms that prohibit them from making any copies of
173
+ your copyrighted material outside their relationship with you.
174
+
175
+ Conveying under any other circumstances is permitted solely under
176
+ the conditions stated below. Sublicensing is not allowed; section 10
177
+ makes it unnecessary.
178
+
179
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
180
+
181
+ No covered work shall be deemed part of an effective technological
182
+ measure under any applicable law fulfilling obligations under article
183
+ 11 of the WIPO copyright treaty adopted on 20 December 1996, or
184
+ similar laws prohibiting or restricting circumvention of such
185
+ measures.
186
+
187
+ When you convey a covered work, you waive any legal power to forbid
188
+ circumvention of technological measures to the extent such circumvention
189
+ is effected by exercising rights under this License with respect to
190
+ the covered work, and you disclaim any intention to limit operation or
191
+ modification of the work as a means of enforcing, against the work's
192
+ users, your or third parties' legal rights to forbid circumvention of
193
+ technological measures.
194
+
195
+ 4. Conveying Verbatim Copies.
196
+
197
+ You may convey verbatim copies of the Program's source code as you
198
+ receive it, in any medium, provided that you conspicuously and
199
+ appropriately publish on each copy an appropriate copyright notice;
200
+ keep intact all notices stating that this License and any
201
+ non-permissive terms added in accord with section 7 apply to the code;
202
+ keep intact all notices of the absence of any warranty; and give all
203
+ recipients a copy of this License along with the Program.
204
+
205
+ You may charge any price or no price for each copy that you convey,
206
+ and you may offer support or warranty protection for a fee.
207
+
208
+ 5. Conveying Modified Source Versions.
209
+
210
+ You may convey a work based on the Program, or the modifications to
211
+ produce it from the Program, in the form of source code under the
212
+ terms of section 4, provided that you also meet all of these conditions:
213
+
214
+ a) The work must carry prominent notices stating that you modified
215
+ it, and giving a relevant date.
216
+
217
+ b) The work must carry prominent notices stating that it is
218
+ released under this License and any conditions added under section
219
+ 7. This requirement modifies the requirement in section 4 to
220
+ "keep intact all notices".
221
+
222
+ c) You must license the entire work, as a whole, under this
223
+ License to anyone who comes into possession of a copy. This
224
+ License will therefore apply, along with any applicable section 7
225
+ additional terms, to the whole of the work, and all its parts,
226
+ regardless of how they are packaged. This License gives no
227
+ permission to license the work in any other way, but it does not
228
+ invalidate such permission if you have separately received it.
229
+
230
+ d) If the work has interactive user interfaces, each must display
231
+ Appropriate Legal Notices; however, if the Program has interactive
232
+ interfaces that do not display Appropriate Legal Notices, your
233
+ work need not make them do so.
234
+
235
+ A compilation of a covered work with other separate and independent
236
+ works, which are not by their nature extensions of the covered work,
237
+ and which are not combined with it such as to form a larger program,
238
+ in or on a volume of a storage or distribution medium, is called an
239
+ "aggregate" if the compilation and its resulting copyright are not
240
+ used to limit the access or legal rights of the compilation's users
241
+ beyond what the individual works permit. Inclusion of a covered work
242
+ in an aggregate does not cause this License to apply to the other
243
+ parts of the aggregate.
244
+
245
+ 6. Conveying Non-Source Forms.
246
+
247
+ You may convey a covered work in object code form under the terms
248
+ of sections 4 and 5, provided that you also convey the
249
+ machine-readable Corresponding Source under the terms of this License,
250
+ in one of these ways:
251
+
252
+ a) Convey the object code in, or embodied in, a physical product
253
+ (including a physical distribution medium), accompanied by the
254
+ Corresponding Source fixed on a durable physical medium
255
+ customarily used for software interchange.
256
+
257
+ b) Convey the object code in, or embodied in, a physical product
258
+ (including a physical distribution medium), accompanied by a
259
+ written offer, valid for at least three years and valid for as
260
+ long as you offer spare parts or customer support for that product
261
+ model, to give anyone who possesses the object code either (1) a
262
+ copy of the Corresponding Source for all the software in the
263
+ product that is covered by this License, on a durable physical
264
+ medium customarily used for software interchange, for a price no
265
+ more than your reasonable cost of physically performing this
266
+ conveying of source, or (2) access to copy the
267
+ Corresponding Source from a network server at no charge.
268
+
269
+ c) Convey individual copies of the object code with a copy of the
270
+ written offer to provide the Corresponding Source. This
271
+ alternative is allowed only occasionally and noncommercially, and
272
+ only if you received the object code with such an offer, in accord
273
+ with subsection 6b.
274
+
275
+ d) Convey the object code by offering access from a designated
276
+ place (gratis or for a charge), and offer equivalent access to the
277
+ Corresponding Source in the same way through the same place at no
278
+ further charge. You need not require recipients to copy the
279
+ Corresponding Source along with the object code. If the place to
280
+ copy the object code is a network server, the Corresponding Source
281
+ may be on a different server (operated by you or a third party)
282
+ that supports equivalent copying facilities, provided you maintain
283
+ clear directions next to the object code saying where to find the
284
+ Corresponding Source. Regardless of what server hosts the
285
+ Corresponding Source, you remain obligated to ensure that it is
286
+ available for as long as needed to satisfy these requirements.
287
+
288
+ e) Convey the object code using peer-to-peer transmission, provided
289
+ you inform other peers where the object code and Corresponding
290
+ Source of the work are being offered to the general public at no
291
+ charge under subsection 6d.
292
+
293
+ A separable portion of the object code, whose source code is excluded
294
+ from the Corresponding Source as a System Library, need not be
295
+ included in conveying the object code work.
296
+
297
+ A "User Product" is either (1) a "consumer product", which means any
298
+ tangible personal property which is normally used for personal, family,
299
+ or household purposes, or (2) anything designed or sold for incorporation
300
+ into a dwelling. In determining whether a product is a consumer product,
301
+ doubtful cases shall be resolved in favor of coverage. For a particular
302
+ product received by a particular user, "normally used" refers to a
303
+ typical or common use of that class of product, regardless of the status
304
+ of the particular user or of the way in which the particular user
305
+ actually uses, or expects or is expected to use, the product. A product
306
+ is a consumer product regardless of whether the product has substantial
307
+ commercial, industrial or non-consumer uses, unless such uses represent
308
+ the only significant mode of use of the product.
309
+
310
+ "Installation Information" for a User Product means any methods,
311
+ procedures, authorization keys, or other information required to install
312
+ and execute modified versions of a covered work in that User Product from
313
+ a modified version of its Corresponding Source. The information must
314
+ suffice to ensure that the continued functioning of the modified object
315
+ code is in no case prevented or interfered with solely because
316
+ modification has been made.
317
+
318
+ If you convey an object code work under this section in, or with, or
319
+ specifically for use in, a User Product, and the conveying occurs as
320
+ part of a transaction in which the right of possession and use of the
321
+ User Product is transferred to the recipient in perpetuity or for a
322
+ fixed term (regardless of how the transaction is characterized), the
323
+ Corresponding Source conveyed under this section must be accompanied
324
+ by the Installation Information. But this requirement does not apply
325
+ if neither you nor any third party retains the ability to install
326
+ modified object code on the User Product (for example, the work has
327
+ been installed in ROM).
328
+
329
+ The requirement to provide Installation Information does not include a
330
+ requirement to continue to provide support service, warranty, or updates
331
+ for a work that has been modified or installed by the recipient, or for
332
+ the User Product in which it has been modified or installed. Access to a
333
+ network may be denied when the modification itself materially and
334
+ adversely affects the operation of the network or violates the rules and
335
+ protocols for communication across the network.
336
+
337
+ Corresponding Source conveyed, and Installation Information provided,
338
+ in accord with this section must be in a format that is publicly
339
+ documented (and with an implementation available to the public in
340
+ source code form), and must require no special password or key for
341
+ unpacking, reading or copying.
342
+
343
+ 7. Additional Terms.
344
+
345
+ "Additional permissions" are terms that supplement the terms of this
346
+ License by making exceptions from one or more of its conditions.
347
+ Additional permissions that are applicable to the entire Program shall
348
+ be treated as though they were included in this License, to the extent
349
+ that they are valid under applicable law. If additional permissions
350
+ apply only to part of the Program, that part may be used separately
351
+ under those permissions, but the entire Program remains governed by
352
+ this License without regard to the additional permissions.
353
+
354
+ When you convey a copy of a covered work, you may at your option
355
+ remove any additional permissions from that copy, or from any part of
356
+ it. (Additional permissions may be written to require their own
357
+ removal in certain cases when you modify the work.) You may place
358
+ additional permissions on material, added by you to a covered work,
359
+ for which you have or can give appropriate copyright permission.
360
+
361
+ Notwithstanding any other provision of this License, for material you
362
+ add to a covered work, you may (if authorized by the copyright holders of
363
+ that material) supplement the terms of this License with terms:
364
+
365
+ a) Disclaiming warranty or limiting liability differently from the
366
+ terms of sections 15 and 16 of this License; or
367
+
368
+ b) Requiring preservation of specified reasonable legal notices or
369
+ author attributions in that material or in the Appropriate Legal
370
+ Notices displayed by works containing it; or
371
+
372
+ c) Prohibiting misrepresentation of the origin of that material, or
373
+ requiring that modified versions of such material be marked in
374
+ reasonable ways as different from the original version; or
375
+
376
+ d) Limiting the use for publicity purposes of names of licensors or
377
+ authors of the material; or
378
+
379
+ e) Declining to grant rights under trademark law for use of some
380
+ trade names, trademarks, or service marks; or
381
+
382
+ f) Requiring indemnification of licensors and authors of that
383
+ material by anyone who conveys the material (or modified versions of
384
+ it) with contractual assumptions of liability to the recipient, for
385
+ any liability that these contractual assumptions directly impose on
386
+ those licensors and authors.
387
+
388
+ All other non-permissive additional terms are considered "further
389
+ restrictions" within the meaning of section 10. If the Program as you
390
+ received it, or any part of it, contains a notice stating that it is
391
+ governed by this License along with a term that is a further
392
+ restriction, you may remove that term. If a license document contains
393
+ a further restriction but permits relicensing or conveying under this
394
+ License, you may add to a covered work material governed by the terms
395
+ of that license document, provided that the further restriction does
396
+ not survive such relicensing or conveying.
397
+
398
+ If you add terms to a covered work in accord with this section, you
399
+ must place, in the relevant source files, a statement of the
400
+ additional terms that apply to those files, or a notice indicating
401
+ where to find the applicable terms.
402
+
403
+ Additional terms, permissive or non-permissive, may be stated in the
404
+ form of a separately written license, or stated as exceptions;
405
+ the above requirements apply either way.
406
+
407
+ 8. Termination.
408
+
409
+ You may not propagate or modify a covered work except as expressly
410
+ provided under this License. Any attempt otherwise to propagate or
411
+ modify it is void, and will automatically terminate your rights under
412
+ this License (including any patent licenses granted under the third
413
+ paragraph of section 11).
414
+
415
+ However, if you cease all violation of this License, then your
416
+ license from a particular copyright holder is reinstated (a)
417
+ provisionally, unless and until the copyright holder explicitly and
418
+ finally terminates your license, and (b) permanently, if the copyright
419
+ holder fails to notify you of the violation by some reasonable means
420
+ prior to 60 days after the cessation.
421
+
422
+ Moreover, your license from a particular copyright holder is
423
+ reinstated permanently if the copyright holder notifies you of the
424
+ violation by some reasonable means, this is the first time you have
425
+ received notice of violation of this License (for any work) from that
426
+ copyright holder, and you cure the violation prior to 30 days after
427
+ your receipt of the notice.
428
+
429
+ Termination of your rights under this section does not terminate the
430
+ licenses of parties who have received copies or rights from you under
431
+ this License. If your rights have been terminated and not permanently
432
+ reinstated, you do not qualify to receive new licenses for the same
433
+ material under section 10.
434
+
435
+ 9. Acceptance Not Required for Having Copies.
436
+
437
+ You are not required to accept this License in order to receive or
438
+ run a copy of the Program. Ancillary propagation of a covered work
439
+ occurring solely as a consequence of using peer-to-peer transmission
440
+ to receive a copy likewise does not require acceptance. However,
441
+ nothing other than this License grants you permission to propagate or
442
+ modify any covered work. These actions infringe copyright if you do
443
+ not accept this License. Therefore, by modifying or propagating a
444
+ covered work, you indicate your acceptance of this License to do so.
445
+
446
+ 10. Automatic Licensing of Downstream Recipients.
447
+
448
+ Each time you convey a covered work, the recipient automatically
449
+ receives a license from the original licensors, to run, modify and
450
+ propagate that work, subject to this License. You are not responsible
451
+ for enforcing compliance by third parties with this License.
452
+
453
+ An "entity transaction" is a transaction transferring control of an
454
+ organization, or substantially all assets of one, or subdividing an
455
+ organization, or merging organizations. If propagation of a covered
456
+ work results from an entity transaction, each party to that
457
+ transaction who receives a copy of the work also receives whatever
458
+ licenses to the work the party's predecessor in interest had or could
459
+ give under the previous paragraph, plus a right to possession of the
460
+ Corresponding Source of the work from the predecessor in interest, if
461
+ the predecessor has it or can get it with reasonable efforts.
462
+
463
+ You may not impose any further restrictions on the exercise of the
464
+ rights granted or affirmed under this License. For example, you may
465
+ not impose a license fee, royalty, or other charge for exercise of
466
+ rights granted under this License, and you may not initiate litigation
467
+ (including a cross-claim or counterclaim in a lawsuit) alleging that
468
+ any patent claim is infringed by making, using, selling, offering for
469
+ sale, or importing the Program or any portion of it.
470
+
471
+ 11. Patents.
472
+
473
+ A "contributor" is a copyright holder who authorizes use under this
474
+ License of the Program or a work on which the Program is based. The
475
+ work thus licensed is called the contributor's "contributor version".
476
+
477
+ A contributor's "essential patent claims" are all patent claims
478
+ owned or controlled by the contributor, whether already acquired or
479
+ hereafter acquired, that would be infringed by some manner, permitted
480
+ by this License, of making, using, or selling its contributor version,
481
+ but do not include claims that would be infringed only as a
482
+ consequence of further modification of the contributor version. For
483
+ purposes of this definition, "control" includes the right to grant
484
+ patent sublicenses in a manner consistent with the requirements of
485
+ this License.
486
+
487
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
488
+ patent license under the contributor's essential patent claims, to
489
+ make, use, sell, offer for sale, import and otherwise run, modify and
490
+ propagate the contents of its contributor version.
491
+
492
+ In the following three paragraphs, a "patent license" is any express
493
+ agreement or commitment, however denominated, not to enforce a patent
494
+ (such as an express permission to practice a patent or covenant not to
495
+ sue for patent infringement). To "grant" such a patent license to a
496
+ party means to make such an agreement or commitment not to enforce a
497
+ patent against the party.
498
+
499
+ If you convey a covered work, knowingly relying on a patent license,
500
+ and the Corresponding Source of the work is not available for anyone
501
+ to copy, free of charge and under the terms of this License, through a
502
+ publicly available network server or other readily accessible means,
503
+ then you must either (1) cause the Corresponding Source to be so
504
+ available, or (2) arrange to deprive yourself of the benefit of the
505
+ patent license for this particular work, or (3) arrange, in a manner
506
+ consistent with the requirements of this License, to extend the patent
507
+ license to downstream recipients. "Knowingly relying" means you have
508
+ actual knowledge that, but for the patent license, your conveying the
509
+ covered work in a country, or your recipient's use of the covered work
510
+ in a country, would infringe one or more identifiable patents in that
511
+ country that you have reason to believe are valid.
512
+
513
+ If, pursuant to or in connection with a single transaction or
514
+ arrangement, you convey, or propagate by procuring conveyance of, a
515
+ covered work, and grant a patent license to some of the parties
516
+ receiving the covered work authorizing them to use, propagate, modify
517
+ or convey a specific copy of the covered work, then the patent license
518
+ you grant is automatically extended to all recipients of the covered
519
+ work and works based on it.
520
+
521
+ A patent license is "discriminatory" if it does not include within
522
+ the scope of its coverage, prohibits the exercise of, or is
523
+ conditioned on the non-exercise of one or more of the rights that are
524
+ specifically granted under this License. You may not convey a covered
525
+ work if you are a party to an arrangement with a third party that is
526
+ in the business of distributing software, under which you make payment
527
+ to the third party based on the extent of your activity of conveying
528
+ the work, and under which the third party grants, to any of the
529
+ parties who would receive the covered work from you, a discriminatory
530
+ patent license (a) in connection with copies of the covered work
531
+ conveyed by you (or copies made from those copies), or (b) primarily
532
+ for and in connection with specific products or compilations that
533
+ contain the covered work, unless you entered into that arrangement,
534
+ or that patent license was granted, prior to 28 March 2007.
535
+
536
+ Nothing in this License shall be construed as excluding or limiting
537
+ any implied license or other defenses to infringement that may
538
+ otherwise be available to you under applicable patent law.
539
+
540
+ 12. No Surrender of Others' Freedom.
541
+
542
+ If conditions are imposed on you (whether by court order, agreement or
543
+ otherwise) that contradict the conditions of this License, they do not
544
+ excuse you from the conditions of this License. If you cannot convey a
545
+ covered work so as to satisfy simultaneously your obligations under this
546
+ License and any other pertinent obligations, then as a consequence you may
547
+ not convey it at all. For example, if you agree to terms that obligate you
548
+ to collect a royalty for further conveying from those to whom you convey
549
+ the Program, the only way you could satisfy both those terms and this
550
+ License would be to refrain entirely from conveying the Program.
551
+
552
+ 13. Use with the GNU Affero General Public License.
553
+
554
+ Notwithstanding any other provision of this License, you have
555
+ permission to link or combine any covered work with a work licensed
556
+ under version 3 of the GNU Affero General Public License into a single
557
+ combined work, and to convey the resulting work. The terms of this
558
+ License will continue to apply to the part which is the covered work,
559
+ but the special requirements of the GNU Affero General Public License,
560
+ section 13, concerning interaction through a network will apply to the
561
+ combination as such.
562
+
563
+ 14. Revised Versions of this License.
564
+
565
+ The Free Software Foundation may publish revised and/or new versions of
566
+ the GNU General Public License from time to time. Such new versions will
567
+ be similar in spirit to the present version, but may differ in detail to
568
+ address new problems or concerns.
569
+
570
+ Each version is given a distinguishing version number. If the
571
+ Program specifies that a certain numbered version of the GNU General
572
+ Public License "or any later version" applies to it, you have the
573
+ option of following the terms and conditions either of that numbered
574
+ version or of any later version published by the Free Software
575
+ Foundation. If the Program does not specify a version number of the
576
+ GNU General Public License, you may choose any version ever published
577
+ by the Free Software Foundation.
578
+
579
+ If the Program specifies that a proxy can decide which future
580
+ versions of the GNU General Public License can be used, that proxy's
581
+ public statement of acceptance of a version permanently authorizes you
582
+ to choose that version for the Program.
583
+
584
+ Later license versions may give you additional or different
585
+ permissions. However, no additional obligations are imposed on any
586
+ author or copyright holder as a result of your choosing to follow a
587
+ later version.
588
+
589
+ 15. Disclaimer of Warranty.
590
+
591
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
592
+ APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
593
+ HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
594
+ OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
595
+ THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
596
+ PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
597
+ IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
598
+ ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
599
+
600
+ 16. Limitation of Liability.
601
+
602
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
603
+ WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
604
+ THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
605
+ GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
606
+ USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
607
+ DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
608
+ PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
609
+ EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
610
+ SUCH DAMAGES.
611
+
612
+ 17. Interpretation of Sections 15 and 16.
613
+
614
+ If the disclaimer of warranty and limitation of liability provided
615
+ above cannot be given local legal effect according to their terms,
616
+ reviewing courts shall apply local law that most closely approximates
617
+ an absolute waiver of all civil liability in connection with the
618
+ Program, unless a warranty or assumption of liability accompanies a
619
+ copy of the Program in return for a fee.
620
+
621
+ END OF TERMS AND CONDITIONS
622
+
623
+ How to Apply These Terms to Your New Programs
624
+
625
+ If you develop a new program, and you want it to be of the greatest
626
+ possible use to the public, the best way to achieve this is to make it
627
+ free software which everyone can redistribute and change under these terms.
628
+
629
+ To do so, attach the following notices to the program. It is safest
630
+ to attach them to the start of each source file to most effectively
631
+ state the exclusion of warranty; and each file should have at least
632
+ the "copyright" line and a pointer to where the full notice is found.
633
+
634
+ <one line to give the program's name and a brief idea of what it does.>
635
+ Copyright (C) <year> <name of author>
636
+
637
+ This program is free software: you can redistribute it and/or modify
638
+ it under the terms of the GNU General Public License as published by
639
+ the Free Software Foundation, either version 3 of the License, or
640
+ (at your option) any later version.
641
+
642
+ This program is distributed in the hope that it will be useful,
643
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
644
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
645
+ GNU General Public License for more details.
646
+
647
+ You should have received a copy of the GNU General Public License
648
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
649
+
650
+ Also add information on how to contact you by electronic and paper mail.
651
+
652
+ If the program does terminal interaction, make it output a short
653
+ notice like this when it starts in an interactive mode:
654
+
655
+ <program> Copyright (C) <year> <name of author>
656
+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657
+ This is free software, and you are welcome to redistribute it
658
+ under certain conditions; type `show c' for details.
659
+
660
+ The hypothetical commands `show w' and `show c' should show the appropriate
661
+ parts of the General Public License. Of course, your program's commands
662
+ might be different; for a GUI interface, you would use an "about box".
663
+
664
+ You should also get your employer (if you work as a programmer) or school,
665
+ if any, to sign a "copyright disclaimer" for the program, if necessary.
666
+ For more information on this, and how to apply and follow the GNU GPL, see
667
+ <https://www.gnu.org/licenses/>.
668
+
669
+ The GNU General Public License does not permit incorporating your program
670
+ into proprietary programs. If your program is a subroutine library, you
671
+ may consider it more useful to permit linking proprietary applications with
672
+ the library. If this is what you want to do, use the GNU Lesser General
673
+ Public License instead of this License. But first, please read
674
+ <https://www.gnu.org/licenses/why-not-lgpl.html>.
LICENSE-APACHE-2.0 ADDED
@@ -0,0 +1,202 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
Makefile ADDED
@@ -0,0 +1,8 @@
 
 
 
 
 
 
 
 
 
1
+ test:
2
+ python -m pytest -q
3
+
4
+ build:
5
+ python -m build
6
+
7
+ lint:
8
+ ruff check src tests vpipe
NOTICE ADDED
@@ -0,0 +1,10 @@
 
 
 
 
 
 
 
 
 
 
 
1
+ videoclean third-party attribution
2
+
3
+ This project can use PP-OCRv5 detector weights derived from PaddleOCR.
4
+
5
+ PP-OCRv5 detector weights
6
+ Copyright (c) PaddlePaddle Authors
7
+ Licensed under the Apache License, Version 2.0.
8
+
9
+ The detector weight is distributed separately from videoclean's GPLv3 source.
10
+ See PROVENANCE.md and LICENSE-APACHE-2.0 for attribution and license terms.
PROVENANCE.md ADDED
@@ -0,0 +1,11 @@
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Detector weight provenance
2
+
3
+ `ppocrv5_det_mob.onnx` is a separately distributed third-party detector weight used by videoclean's optional automatic text detection.
4
+
5
+ - Upstream family: PP-OCRv5 mobile detector
6
+ - Upstream project: [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)
7
+ - Upstream license: Apache License 2.0
8
+ - Local filename: `ppocrv5_det_mob.onnx`
9
+ - SHA-256: `4d97c44a20d30a81aad087d6a396b08f786c4635742afc391f6621f5c6ae78ae`
10
+
11
+ The exact conversion provenance of the local ONNX file should be confirmed before a public release. Do not alter the file without updating this document and publishing a prominent modification notice.
README.md ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # videoclean
2
+
3
+ Open-source, CPU-friendly video cleanup for hardcoded subtitles, watermarks, logos, and timestamps.
4
+
5
+ `videoclean` uses OpenCV's Telea or Navier–Stokes inpainting with a stable mask applied to every frame. It has no PyTorch, ONNX Runtime, GPU, or model-weight dependency for inpainting. FFmpeg must be installed and available on `PATH`.
6
+
7
+ Automatic detection uses the separately distributed PP-OCRv5 detector weight. The weight is Apache-2.0 licensed and hosted at [Hugging Face](https://huggingface.co/stevenlearns/videoclean-detector); see [NOTICE](NOTICE), [LICENSE-APACHE-2.0](LICENSE-APACHE-2.0), and [PROVENANCE.md](PROVENANCE.md). Manual masks work without downloading detector weights.
8
+
9
+ The source code is GPLv3; third-party detector weights retain their separate license.
10
+
11
+ ## Development
12
+
13
+ ```bash
14
+ python -m pip install -e '.[dev]'
15
+ python -m pytest -q
16
+ python -m build
17
+ ```
18
+
19
+ Canonical source: [GitHub](https://github.com/oohfixer/videoclean).
20
+
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ pip install videoclean
26
+ ```
27
+
28
+ Optional OCR support:
29
+
30
+ ```bash
31
+ pip install 'videoclean[ocr]'
32
+ ```
33
+
34
+ ## Usage
35
+
36
+ ```bash
37
+ videoclean clean input.mp4 -o output-directory
38
+ vpipe -y --clean input.mp4
39
+ ```
40
+
41
+ For a reviewed mask:
42
+
43
+ ```bash
44
+ videoclean clean input.mp4 -m mask.png -o output-directory \
45
+ --inpaint-method telea --inpaint-radius 5 --inpaint-dilate 2
46
+ ```
47
+
48
+ No-candidate detection is a successful passthrough: the input is copied to the output directory unchanged. Use `--preview` to inspect detection artifacts before processing.
49
+
50
+ ## License
51
+
52
+ GPLv3. See `LICENSE`.
pyproject.toml ADDED
@@ -0,0 +1,28 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "videoclean"
7
+ version = "0.1.0"
8
+ description = "OpenCV-only removal of hardcoded subtitles, watermarks, logos, and timestamps"
9
+ license = { file = "LICENSE" }
10
+ requires-python = ">=3.10"
11
+ dependencies = ["opencv-python-headless>=4.5,<5", "numpy", "tqdm"]
12
+ classifiers = ["License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Programming Language :: Python :: 3"]
13
+
14
+ [project.optional-dependencies]
15
+ ocr = ["rapidocr-onnxruntime"]
16
+ dev = ["pytest", "ruff", "build"]
17
+
18
+ [project.scripts]
19
+ videoclean = "videoclean.cli:main"
20
+
21
+ [tool.hatch.build.targets.wheel]
22
+ packages = ["src/videoclean"]
23
+
24
+ [tool.hatch.build.targets.sdist]
25
+ include = ["/src", "/tests", "/LICENSE", "/LICENSE-APACHE-2.0", "/NOTICE", "/PROVENANCE.md", "/README.md", "/pyproject.toml"]
26
+
27
+ [tool.pytest.ini_options]
28
+ pythonpath = ["src"]
src/videoclean/__init__.py ADDED
@@ -0,0 +1,9 @@
 
 
 
 
 
 
 
 
 
 
1
+ """OpenCV-only video overlay removal."""
2
+ from videoclean.api import CancellationToken, ProgressEvent, WipeRequest, WipeResult
3
+ from videoclean.engine import WipeEngine, remove_text
4
+ from videoclean.errors import BackendUnavailableError, InvalidInputError, ProcessingCancelledError, ProcessingError, WipeError
5
+ from videoclean.inpainters import InpaintJob, InpaintOutcome, Inpainter, OpenCVInpainter, get_registry, register_inpainter
6
+ from videoclean.plan import Segment, Source, Track, WipePlan, build_wipe_plan, compute_source, is_temporal, load_wipe_plan, save_wipe_plan, validate_plan
7
+
8
+ __version__ = "0.1.0"
9
+ __all__ = ["CancellationToken", "ProgressEvent", "WipeRequest", "WipeResult", "WipeEngine", "remove_text", "WipeError", "InvalidInputError", "BackendUnavailableError", "ProcessingCancelledError", "ProcessingError", "InpaintJob", "InpaintOutcome", "Inpainter", "OpenCVInpainter", "get_registry", "register_inpainter", "Segment", "Source", "Track", "WipePlan", "build_wipe_plan", "compute_source", "is_temporal", "load_wipe_plan", "save_wipe_plan", "validate_plan"]
src/videoclean/__pycache__/__init__.cpython-314.pyc ADDED
Binary file (1.19 kB). View file
 
src/videoclean/__pycache__/api.cpython-314.pyc ADDED
Binary file (6.27 kB). View file
 
src/videoclean/__pycache__/cli.cpython-314.pyc ADDED
Binary file (7.32 kB). View file
 
src/videoclean/__pycache__/detect.cpython-314.pyc ADDED
Binary file (81 kB). View file
 
src/videoclean/__pycache__/engine.cpython-314.pyc ADDED
Binary file (30.2 kB). View file
 
src/videoclean/__pycache__/errors.cpython-314.pyc ADDED
Binary file (2.69 kB). View file
 
src/videoclean/__pycache__/ocr.cpython-314.pyc ADDED
Binary file (4.07 kB). View file
 
src/videoclean/__pycache__/plan.cpython-314.pyc ADDED
Binary file (47.8 kB). View file
 
src/videoclean/__pycache__/weights.cpython-314.pyc ADDED
Binary file (4.36 kB). View file
 
src/videoclean/api.py ADDED
@@ -0,0 +1,103 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Public request, result, progress, and cancellation contracts."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ import threading
6
+ from dataclasses import asdict, dataclass, field
7
+ from typing import Any, Callable, Mapping, Optional, Sequence, Union
8
+
9
+ from videoclean.errors import ProcessingCancelledError
10
+
11
+ Pathish = Union[str, os.PathLike]
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class WipeRequest:
16
+ """One video-cleanup request.
17
+
18
+ Model configuration belongs to :class:`WipeEngine`; this object contains
19
+ only per-video inputs so one loaded engine can be reused across a batch.
20
+ """
21
+
22
+ video: Pathish
23
+ output_dir: Pathish = "result/"
24
+ mask: Optional[Pathish] = None
25
+ detector: Any = None
26
+ targets: Sequence[str] = ()
27
+ intent: Optional[str] = None
28
+ agent: Optional[str] = None
29
+ regions: Sequence[str] = ()
30
+ preview: bool = False
31
+ confirm: bool = False
32
+ detect_mode: Optional[str] = None
33
+ ocr: Optional[str] = None
34
+ detector_mode: Optional[str] = None
35
+ plan: Any = None # a WipePlan, a path to wipe_plan.json, or None; mutually exclusive with mask
36
+
37
+
38
+ @dataclass(frozen=True)
39
+ class ProgressEvent:
40
+ """Structured progress emitted by :meth:`WipeEngine.run` and ``plan``."""
41
+
42
+ phase: str
43
+ completed: int = 0
44
+ total: int = 0
45
+ message: Optional[str] = None
46
+
47
+ @property
48
+ def fraction(self) -> Optional[float]:
49
+ if self.total <= 0:
50
+ return None
51
+ return min(1.0, max(0.0, self.completed / self.total))
52
+
53
+ def to_dict(self) -> dict:
54
+ return asdict(self)
55
+
56
+
57
+ @dataclass(frozen=True)
58
+ class WipeResult:
59
+ """Structured outcome of one SDK request."""
60
+
61
+ output_path: str
62
+ backend: Optional[str]
63
+ mask_source: str
64
+ artifacts: Sequence[str] = ()
65
+ timings: Mapping[str, float] = field(default_factory=dict)
66
+ warnings: Sequence[str] = ()
67
+ preview: bool = False
68
+
69
+ def to_dict(self) -> dict:
70
+ return {
71
+ "output_path": self.output_path,
72
+ "backend": self.backend,
73
+ "mask_source": self.mask_source,
74
+ "artifacts": list(self.artifacts),
75
+ "timings": dict(self.timings),
76
+ "warnings": list(self.warnings),
77
+ "preview": self.preview,
78
+ }
79
+
80
+
81
+ class CancellationToken:
82
+ """Thread-safe cooperative cancellation flag.
83
+
84
+ Cancellation is observed at VideoWipe phase and segment boundaries. It
85
+ does not forcibly interrupt a single backend inference call.
86
+ """
87
+
88
+ def __init__(self) -> None:
89
+ self._event = threading.Event()
90
+
91
+ def cancel(self) -> None:
92
+ self._event.set()
93
+
94
+ @property
95
+ def is_cancelled(self) -> bool:
96
+ return self._event.is_set()
97
+
98
+ def raise_if_cancelled(self) -> None:
99
+ if self.is_cancelled:
100
+ raise ProcessingCancelledError("Video cleanup was cancelled")
101
+
102
+
103
+ ProgressCallback = Callable[[ProgressEvent], None]
src/videoclean/cli.py ADDED
@@ -0,0 +1,134 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """CLI entry point for videoclean."""
2
+ import argparse
3
+ import sys
4
+
5
+ from videoclean.api import ProgressEvent, WipeRequest
6
+ from videoclean.engine import WipeEngine
7
+
8
+
9
+ def _print_progress(event: ProgressEvent) -> None:
10
+ labels = {
11
+ "prepare": "Preparing",
12
+ "detect": "Detecting overlay text",
13
+ "candidates": "Analyzing candidates",
14
+ "mask": "Building removal mask",
15
+ "plan": "Building removal plan",
16
+ "refine": "Refining temporal mask",
17
+ "persist": "Saving detection artifacts",
18
+ "inpaint": "Reconstructing background",
19
+ "validate": "Validating output",
20
+ "complete": "Complete",
21
+ "error": "Failed",
22
+ }
23
+ label = labels.get(event.phase, event.phase.title())
24
+ suffix = f" — {event.message}" if event.message else ""
25
+ if event.total > 1:
26
+ # Avoid flooding the terminal for per-frame refinement events.
27
+ if event.phase == "refine" and not event.message:
28
+ return
29
+ print(f"[videoclean] {label}: {event.completed}/{event.total}{suffix}", flush=True)
30
+ else:
31
+ print(f"[videoclean] {label}{suffix}", flush=True)
32
+
33
+
34
+ def _build_parser():
35
+ parser = argparse.ArgumentParser(
36
+ prog="videoclean",
37
+ description="OpenCV-only removal of hardcoded subtitles and overlays",
38
+ )
39
+ subparsers = parser.add_subparsers(dest="command")
40
+
41
+ clean = subparsers.add_parser("clean", help="Detect and remove subtitles or overlays")
42
+ clean.add_argument("video", help="Input video path")
43
+ mask_or_plan = clean.add_mutually_exclusive_group()
44
+ mask_or_plan.add_argument("-m", "--mask", help="Mask image path; skip detection")
45
+ mask_or_plan.add_argument("--plan", help="Existing wipe_plan.json")
46
+ clean.add_argument("-o", "--output", default="result/", help="Output directory")
47
+ clean.add_argument("-g", "--gap", type=int, default=10, help="Compatibility segment-size option")
48
+ clean.add_argument("--verbose", action="store_true")
49
+ clean.add_argument("-d", "--dual", action="store_true", help="Show original beside cleaned video")
50
+ clean.add_argument("--target", action="append", default=None)
51
+ clean.add_argument("--region", action="append", default=None)
52
+ clean.add_argument("--intent", default=None)
53
+ clean.add_argument("--preview", action="store_true")
54
+ clean.add_argument("--confirm", action="store_true")
55
+ clean.add_argument("--detect-mode", choices=["fast", "balanced", "sensitive"], default="balanced")
56
+ clean.add_argument("--ocr", choices=["auto", "off", "rapidocr"], default="auto")
57
+ clean.add_argument("--detector", dest="detector_mode", choices=["dbnet", "hybrid"], default="dbnet")
58
+ clean.add_argument("--inpaint-method", choices=["telea", "ns"], default="telea")
59
+ clean.add_argument("--inpaint-radius", type=float, default=3.0)
60
+ clean.add_argument("--inpaint-dilate", type=int, default=0)
61
+
62
+ # Keep detext as a small compatibility alias for explicit-mask workflows.
63
+ detext = subparsers.add_parser("detext", help="Alias for clean")
64
+ detext.add_argument("-v", "--video", required=True)
65
+ detext.add_argument("-m", "--mask", default=None)
66
+ detext.add_argument("-o", "--output", default="result/")
67
+ detext.add_argument("-g", "--gap", type=int, default=10)
68
+ detext.add_argument("-d", "--dual", action="store_true")
69
+ detext.add_argument("--inpaint-method", choices=["telea", "ns"], default="telea")
70
+ detext.add_argument("--inpaint-radius", type=float, default=3.0)
71
+ detext.add_argument("--inpaint-dilate", type=int, default=0)
72
+ return parser
73
+
74
+
75
+ def main():
76
+ parser = _build_parser()
77
+ args = parser.parse_args()
78
+
79
+ if not args.command:
80
+ parser.print_help()
81
+ sys.exit(1)
82
+
83
+ if args.command == "detext":
84
+ args.command = "detext"
85
+ args.detect_mode = "balanced"
86
+ args.ocr = "off"
87
+ args.detector_mode = "dbnet"
88
+ args.target = None
89
+ args.region = None
90
+ args.intent = None
91
+ args.preview = False
92
+ args.confirm = False
93
+ args.plan = None
94
+ args.verbose = False
95
+
96
+ engine = WipeEngine(
97
+ task=args.command,
98
+ gap=args.gap,
99
+ dual=args.dual,
100
+ model_options={
101
+ "method": args.inpaint_method,
102
+ "radius": args.inpaint_radius,
103
+ "dilate": args.inpaint_dilate,
104
+ },
105
+ detect_mode=getattr(args, "detect_mode", "balanced"),
106
+ ocr=getattr(args, "ocr", "auto"),
107
+ verbose=getattr(args, "verbose", False),
108
+ )
109
+ try:
110
+ engine.run(
111
+ WipeRequest(
112
+ video=args.video,
113
+ mask=args.mask,
114
+ output_dir=args.output,
115
+ targets=getattr(args, "target", None) or (),
116
+ intent=getattr(args, "intent", None),
117
+ agent=getattr(args, "agent", None),
118
+ regions=getattr(args, "region", None) or (),
119
+ preview=getattr(args, "preview", False),
120
+ confirm=getattr(args, "confirm", False),
121
+ plan=getattr(args, "plan", None),
122
+ detector_mode=getattr(args, "detector_mode", "dbnet"),
123
+ ),
124
+ on_progress=_print_progress,
125
+ )
126
+ except Exception as exc:
127
+ print(f"videoclean: {exc}", file=sys.stderr)
128
+ sys.exit(1)
129
+ finally:
130
+ engine.cleanup()
131
+
132
+
133
+ if __name__ == "__main__":
134
+ main()
src/videoclean/detect.py ADDED
@@ -0,0 +1,1538 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Auto-detect text regions in video for mask generation.
2
+
3
+ This module provides:
4
+
5
+ - :class:`TextDetector` — a protocol for pluggable text-region detectors.
6
+ Implement this to integrate custom detection models or external APIs.
7
+ - :class:`DBNetDetector` — built-in detector that loads DBNet-family ONNX
8
+ models via OpenCV DNN (zero extra dependencies beyond the default
9
+ ``opencv-python-headless`` runtime).
10
+ - :func:`detect_subtitle_mask` — high-level function that samples frames,
11
+ runs detection, and produces a binary mask.
12
+
13
+ Quick start (mask auto-detected)::
14
+
15
+ from videoclean import remove_text
16
+ remove_text("video.mp4")
17
+
18
+ Custom detector::
19
+
20
+ from videoclean.detect import detect_subtitle_mask, TextDetector, TextBox
21
+
22
+ class MyDetector:
23
+ def detect(self, frame):
24
+ # call your API or model here
25
+ return [TextBox(points=..., confidence=...)]
26
+
27
+ mask = detect_subtitle_mask("video.mp4", detector=MyDetector())
28
+ """
29
+ from __future__ import annotations
30
+
31
+ import logging
32
+ import json
33
+ import os
34
+ import re
35
+ from dataclasses import dataclass, field
36
+ from typing import Iterable, List, Literal, Protocol, runtime_checkable
37
+
38
+ import cv2
39
+ import numpy as np
40
+
41
+ logger = logging.getLogger(__name__)
42
+
43
+
44
+ # ── Data types ───────────────────────────────────────────────────────────────
45
+
46
+ @dataclass
47
+ class TextBox:
48
+ """A detected text region.
49
+
50
+ Attributes:
51
+ points: ``(N, 2)`` float array of polygon vertices (pixel coords).
52
+ confidence: Detection confidence in ``[0, 1]``.
53
+ """
54
+
55
+ points: np.ndarray
56
+ confidence: float
57
+ text: str = ""
58
+
59
+
60
+ TargetType = Literal[
61
+ "subtitle",
62
+ "timestamp",
63
+ "watermark",
64
+ "logo",
65
+ "scene_text",
66
+ "unknown_text",
67
+ "region",
68
+ ]
69
+
70
+
71
+ @dataclass
72
+ class CleanCandidate:
73
+ """A candidate object that can be removed from a video."""
74
+
75
+ id: str
76
+ type: TargetType
77
+ label: str
78
+ bbox: tuple[int, int, int, int]
79
+ confidence: float
80
+ frame_fraction: float
81
+ reason: str
82
+ default_remove: bool
83
+ text_samples: list[str] = field(default_factory=list)
84
+ presence_frames: list[int] = field(default_factory=list)
85
+ mask: np.ndarray | None = field(default=None, repr=False)
86
+ # Runtime-only evidence used to sharpen temporal plan segments. It is
87
+ # deliberately absent from to_dict()/WipePlan v1 serialization.
88
+ temporal_sample_indices: list[int] = field(default_factory=list, repr=False)
89
+ detector_backed: bool = field(default=False, repr=False)
90
+
91
+ def to_dict(self) -> dict:
92
+ """Return a JSON-safe representation without the binary mask."""
93
+ return {
94
+ "id": self.id,
95
+ "type": self.type,
96
+ "label": self.label,
97
+ "bbox": list(self.bbox),
98
+ "confidence": round(float(self.confidence), 3),
99
+ "frame_fraction": round(float(self.frame_fraction), 3),
100
+ "reason": self.reason,
101
+ "default_remove": self.default_remove,
102
+ "text_samples": self.text_samples[:5],
103
+ "presence_frames": list(self.presence_frames),
104
+ }
105
+
106
+
107
+ @dataclass
108
+ class CleanDetectionResult:
109
+ """Result of clean-target detection."""
110
+
111
+ candidates: list[CleanCandidate]
112
+ frame_shape: tuple[int, int]
113
+ sample_indices: list[int] = field(default_factory=list)
114
+ preview_frame: np.ndarray | None = field(default=None, repr=False)
115
+ detector: TextDetector | None = field(default=None, repr=False)
116
+
117
+
118
+ # ── Detector protocol ────────────────────────────────────────────────────────
119
+
120
+ @runtime_checkable
121
+ class TextDetector(Protocol):
122
+ """Protocol for pluggable text-region detectors.
123
+
124
+ Implement this to use a custom detection model or an external API.
125
+ The only required method is :meth:`detect`.
126
+
127
+ Example — wrapping a remote OCR API::
128
+
129
+ import requests
130
+
131
+ class APIDetector:
132
+ def __init__(self, endpoint: str, api_key: str):
133
+ self.endpoint = endpoint
134
+ self.api_key = api_key
135
+
136
+ def detect(self, frame: np.ndarray) -> list[TextBox]:
137
+ _, buf = cv2.imencode(".png", frame)
138
+ resp = requests.post(
139
+ self.endpoint,
140
+ headers={"Authorization": f"Bearer {self.api_key}"},
141
+ files={"image": buf.tobytes()},
142
+ )
143
+ resp.raise_for_status()
144
+ return [
145
+ TextBox(
146
+ points=np.array(d["polygon"], dtype=np.float32),
147
+ confidence=d["score"],
148
+ )
149
+ for d in resp.json()["detections"]
150
+ ]
151
+ """
152
+
153
+ def detect(self, frame: np.ndarray) -> List[TextBox]:
154
+ """Detect text regions in a BGR ``uint8`` frame.
155
+
156
+ Args:
157
+ frame: ``(H, W, 3)`` BGR image.
158
+
159
+ Returns:
160
+ List of :class:`TextBox`.
161
+ """
162
+ ...
163
+
164
+
165
+ # ── Built-in DBNet detector ──────────────────────────────────────────────────
166
+
167
+ class DBNetDetector:
168
+ """DBNet-family text detector using OpenCV DNN.
169
+
170
+ Loads an ONNX model and performs text detection with configurable
171
+ post-processing. Works with DBNet models exported from PaddleOCR,
172
+ MMOCR, or other frameworks that output a probability map.
173
+
174
+ Tries to use ``cv2.dnn.TextDetectionModel_DB`` (OpenCV >= 4.5.4)
175
+ for built-in post-processing; falls back to a manual implementation
176
+ if the high-level API is unavailable.
177
+
178
+ Args:
179
+ weight_path: Path to the ONNX model file.
180
+ input_size: ``(width, height)`` — both should be multiples of 32.
181
+ bin_thresh: Threshold for binarising the probability map.
182
+ box_thresh: Minimum mean probability inside a contour.
183
+ unclip_ratio: Factor to expand each detected box.
184
+ mean: Channel means for normalisation (ImageNet defaults).
185
+ scale: Pixel-scale factor (``1/255`` normalises to ``[0, 1]``).
186
+ """
187
+
188
+ def __init__(
189
+ self,
190
+ weight_path: str,
191
+ input_size: tuple[int, int] = (640, 640),
192
+ bin_thresh: float = 0.3,
193
+ box_thresh: float = 0.5,
194
+ unclip_ratio: float = 1.5,
195
+ mean: tuple[float, ...] = (0.485, 0.456, 0.406),
196
+ scale: float = 1.0 / 255.0,
197
+ adaptive: bool = True,
198
+ ):
199
+ self._input_w, self._input_h = input_size
200
+ self._bin_thresh = bin_thresh
201
+ self._box_thresh = box_thresh
202
+ self._unclip_ratio = unclip_ratio
203
+ self._mean = mean
204
+ self._scale = scale
205
+ self._adaptive = adaptive
206
+
207
+ self._net = cv2.dnn.readNetFromONNX(weight_path)
208
+
209
+ # Cache for adaptive input-size computation
210
+ self._cached_frame_dims: tuple[int, int] | None = None
211
+ self._cached_input_size: tuple[int, int] | None = None
212
+
213
+ # Try high-level OpenCV API (>= 4.5.4)
214
+ self._hl_model = None
215
+ try:
216
+ model = cv2.dnn.TextDetectionModel_DB(self._net)
217
+ model.setInputParams(
218
+ scale=scale, size=input_size, mean=mean, swapRB=True,
219
+ )
220
+ model.setBinaryThreshold(bin_thresh)
221
+ model.setPolygonThreshold(box_thresh)
222
+ model.setUnclipRatio(unclip_ratio)
223
+ model.setMaxCandidates(200)
224
+ self._hl_model = model
225
+ except (AttributeError, cv2.error):
226
+ pass
227
+
228
+ def _adaptive_input_size(self, frame_h: int, frame_w: int) -> tuple[int, int]:
229
+ """Compute model input size that matches the frame aspect ratio.
230
+
231
+ Keeps the total pixel budget close to ``input_size`` area while
232
+ choosing width/height that match the frame's aspect ratio.
233
+ This avoids the resolution loss that occurs when a widescreen
234
+ frame is squeezed into a square input.
235
+ """
236
+ dims = (frame_h, frame_w)
237
+ if self._cached_frame_dims == dims and self._cached_input_size is not None:
238
+ return self._cached_input_size
239
+
240
+ aspect = frame_w / frame_h
241
+ target_area = self._input_w * self._input_h
242
+ new_w = int(np.sqrt(target_area * aspect))
243
+ new_h = int(new_w / aspect)
244
+ # Round up to multiples of 32 (required by the model)
245
+ new_w = ((new_w + 31) // 32) * 32
246
+ new_h = ((new_h + 31) // 32) * 32
247
+
248
+ result = (new_w, new_h)
249
+ self._cached_frame_dims = dims
250
+ self._cached_input_size = result
251
+ return result
252
+
253
+ def detect(self, frame: np.ndarray) -> List[TextBox]:
254
+ """Run text detection on a single frame."""
255
+ h, w = frame.shape[:2]
256
+ if self._adaptive:
257
+ input_w, input_h = self._adaptive_input_size(h, w)
258
+ else:
259
+ input_w, input_h = self._input_w, self._input_h
260
+
261
+ if self._hl_model is not None:
262
+ # Reconfigure input size when adaptive or first call
263
+ if self._adaptive:
264
+ self._hl_model.setInputParams(
265
+ scale=self._scale, size=(input_w, input_h),
266
+ mean=self._mean, swapRB=True,
267
+ )
268
+ boxes = self._detect_hl(frame)
269
+ if boxes:
270
+ return boxes
271
+ # High-level API returned nothing — fall back to manual post-processing
272
+ logger.debug("High-level DB API returned 0 boxes; falling back to manual path")
273
+ return self._detect_manual(frame, input_w=input_w, input_h=input_h)
274
+
275
+ def _detect_hl(self, frame: np.ndarray) -> List[TextBox]:
276
+ detections, confidences = self._hl_model.detect(frame)
277
+ boxes: list[TextBox] = []
278
+ for pts, conf in zip(detections, confidences):
279
+ pts = pts.squeeze()
280
+ if pts.ndim != 2 or pts.shape[0] < 3:
281
+ continue
282
+ boxes.append(
283
+ TextBox(points=pts.astype(np.float32), confidence=float(conf))
284
+ )
285
+ return boxes
286
+
287
+ def _detect_manual(
288
+ self,
289
+ frame: np.ndarray,
290
+ input_w: int | None = None,
291
+ input_h: int | None = None,
292
+ ) -> List[TextBox]:
293
+ iw = input_w or self._input_w
294
+ ih = input_h or self._input_h
295
+ h, w = frame.shape[:2]
296
+ ratio = min(iw / w, ih / h)
297
+ new_w, new_h = int(w * ratio), int(h * ratio)
298
+
299
+ resized = cv2.resize(frame, (new_w, new_h))
300
+ padded = np.full((ih, iw, 3), 128, dtype=np.uint8)
301
+ padded[:new_h, :new_w] = resized
302
+
303
+ blob = cv2.dnn.blobFromImage(
304
+ padded,
305
+ scalefactor=self._scale,
306
+ size=(iw, ih),
307
+ mean=self._mean,
308
+ swapRB=True,
309
+ )
310
+ self._net.setInput(blob)
311
+ out = self._net.forward()
312
+
313
+ # Probability map: (1, 1, H', W') or (1, 2, H', W')
314
+ prob = out[0, 0]
315
+ # Apply sigmoid if raw logits
316
+ if prob.max() > 1.0 or prob.min() < 0.0:
317
+ prob = 1.0 / (1.0 + np.exp(-prob))
318
+
319
+ prob = cv2.resize(prob, (w, h))
320
+
321
+ binary = (prob > self._bin_thresh).astype(np.uint8)
322
+ contours, _ = cv2.findContours(
323
+ binary, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE
324
+ )
325
+
326
+ boxes: list[TextBox] = []
327
+ for cnt in contours:
328
+ if len(cnt) < 4:
329
+ continue
330
+ rect = cv2.minAreaRect(cnt)
331
+ bw, bh = rect[1]
332
+ if min(bw, bh) < 3:
333
+ continue
334
+
335
+ cnt_mask = np.zeros(prob.shape, dtype=np.uint8)
336
+ cv2.fillPoly(cnt_mask, [cnt], 1)
337
+ score = float(cv2.mean(prob, cnt_mask)[0])
338
+ if score < self._box_thresh:
339
+ continue
340
+
341
+ # Approximate unclip by scaling around box centre
342
+ pts = cv2.boxPoints(rect).astype(np.float32)
343
+ centre = pts.mean(axis=0)
344
+ expanded = centre + (pts - centre) * self._unclip_ratio
345
+
346
+ boxes.append(TextBox(points=expanded, confidence=score))
347
+ return boxes
348
+
349
+
350
+ class HybridTextDetector:
351
+ """Use DBNet first and RapidOCR only when DBNet misses a frame.
352
+
353
+ RapidOCR is intentionally a fallback rather than a second detector on every
354
+ frame: this keeps the normal path fast while recovering small or unusual
355
+ overlays. The object implements :class:`TextDetector` and is therefore
356
+ also safe to use during temporal refinement.
357
+ """
358
+
359
+ def __init__(self, primary: TextDetector, min_confidence: float = 0.35):
360
+ self.primary = primary
361
+ self.min_confidence = float(min_confidence)
362
+ try:
363
+ from videoclean.ocr import recognize_regions
364
+ except ImportError as exc:
365
+ raise RuntimeError(
366
+ "Hybrid detection requires rapidocr-onnxruntime. "
367
+ "Install it with: pip install videoclean[ocr]"
368
+ ) from exc
369
+ self._recognize_regions = recognize_regions
370
+ self.last_source = "primary"
371
+ self.stats = {"primary": 0, "ocr": 0, "errors": 0}
372
+
373
+ @staticmethod
374
+ def _overlap(a: TextBox, b: TextBox, width: int, height: int) -> float:
375
+ ax1, ay1, ax2, ay2 = _bbox(a.points, width, height)
376
+ bx1, by1, bx2, by2 = _bbox(b.points, width, height)
377
+ ix1, iy1 = max(ax1, bx1), max(ay1, by1)
378
+ ix2, iy2 = min(ax2, bx2), min(ay2, by2)
379
+ inter = max(0, ix2 - ix1 + 1) * max(0, iy2 - iy1 + 1)
380
+ area_a = max(1, ax2 - ax1 + 1) * max(1, ay2 - ay1 + 1)
381
+ area_b = max(1, bx2 - bx1 + 1) * max(1, by2 - by1 + 1)
382
+ return inter / max(1, area_a + area_b - inter)
383
+
384
+ def detect(self, frame: np.ndarray) -> List[TextBox]:
385
+ try:
386
+ primary_boxes = list(self.primary.detect(frame) or [])
387
+ except Exception:
388
+ self.stats["errors"] += 1
389
+ primary_boxes = []
390
+ if primary_boxes:
391
+ self.stats["primary"] += len(primary_boxes)
392
+ self.last_source = "primary"
393
+ return primary_boxes
394
+
395
+ try:
396
+ regions = self._recognize_regions(frame)
397
+ except Exception as exc:
398
+ self.stats["errors"] += 1
399
+ logger.debug("RapidOCR fallback failed: %s", exc)
400
+ self.last_source = "none"
401
+ return []
402
+
403
+ h, w = frame.shape[:2]
404
+ boxes: list[TextBox] = []
405
+ for region in regions:
406
+ if region.confidence < self.min_confidence:
407
+ continue
408
+ points = np.asarray(region.points, dtype=np.float32)
409
+ if points.shape[0] < 3:
410
+ continue
411
+ box = TextBox(points=points, confidence=region.confidence, text=region.text)
412
+ if any(self._overlap(box, existing, w, h) > 0.5 for existing in boxes):
413
+ continue
414
+ boxes.append(box)
415
+ self.stats["ocr"] += len(boxes)
416
+ self.last_source = "ocr" if boxes else "none"
417
+ return boxes
418
+
419
+
420
+ # ── Mask generation pipeline ─────────────────────────────────────────────────
421
+
422
+ def _sample_frames_with_indices(
423
+ video_path: str, count: int = 30
424
+ ) -> list[tuple[int, np.ndarray]]:
425
+ """Uniformly sample *count* frames, returning ``(frame_index, frame)`` pairs.
426
+
427
+ The frame indices are the real positions in the source video, preserved so
428
+ callers can derive temporal evidence (which frames a candidate was present
429
+ on). Only successfully read frames are returned, in ascending index order.
430
+ """
431
+ cap = cv2.VideoCapture(video_path)
432
+ if not cap.isOpened():
433
+ raise ValueError(f"Cannot open video: {video_path}")
434
+
435
+ total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
436
+ if total <= 0:
437
+ cap.release()
438
+ raise ValueError(f"Cannot determine frame count: {video_path}")
439
+
440
+ count = min(count, total)
441
+ indices = sorted(set(np.linspace(0, total - 1, count, dtype=int)))
442
+
443
+ indexed: list[tuple[int, np.ndarray]] = []
444
+ for idx in indices:
445
+ cap.set(cv2.CAP_PROP_POS_FRAMES, idx)
446
+ ok, frame = cap.read()
447
+ if ok:
448
+ indexed.append((int(idx), frame))
449
+ cap.release()
450
+ return indexed
451
+
452
+
453
+ def _sample_frames(video_path: str, count: int = 30) -> List[np.ndarray]:
454
+ """Uniformly sample *count* frames from a video (drops frame indices)."""
455
+ return [frame for _, frame in _sample_frames_with_indices(video_path, count)]
456
+
457
+
458
+ def detect_subtitle_mask(
459
+ video_path: str,
460
+ detector: TextDetector | None = None,
461
+ sample_count: int = 30,
462
+ consistency: float = 0.6,
463
+ ) -> np.ndarray:
464
+ """Auto-detect subtitle regions and return a binary mask.
465
+
466
+ 1. Uniformly sample *sample_count* frames from the video.
467
+ 2. Run *detector* :meth:`~TextDetector.detect` on each frame.
468
+ 3. Build a per-pixel frequency map (fraction of frames with detected
469
+ text at that location).
470
+ 4. Threshold at *consistency* and apply morphological cleanup.
471
+
472
+ Args:
473
+ video_path: Path to the input video.
474
+ detector: A :class:`TextDetector`. ``None`` uses the built-in
475
+ :class:`DBNetDetector` with auto-downloaded weights.
476
+ sample_count: Frames to sample from the video.
477
+ consistency: Fraction (0–1) of frames a pixel must appear in.
478
+ Higher values reduce false positives but may miss short subtitles.
479
+
480
+ Returns:
481
+ ``(H, W, 1)`` uint8 array with values in ``{0, 1}`` —
482
+ same format as :func:`~videoclean.tasks.base.read_mask`.
483
+
484
+ Raises:
485
+ ValueError: Cannot read the video.
486
+ RuntimeError: Detection fails on every sampled frame.
487
+ """
488
+ if detector is None:
489
+ detector = _default_detector()
490
+
491
+ print(f"Sampling {sample_count} frames for mask detection...")
492
+ frames = _sample_frames(video_path, sample_count)
493
+ if not frames:
494
+ raise ValueError(f"No frames could be read from: {video_path}")
495
+
496
+ h, w = frames[0].shape[:2]
497
+
498
+ # Accumulate detection frequency
499
+ freq = np.zeros((h, w), dtype=np.float32)
500
+ n_valid = 0
501
+
502
+ for i, frame in enumerate(frames):
503
+ try:
504
+ boxes = detector.detect(frame)
505
+ except Exception as exc:
506
+ logger.warning("Detection failed on frame %d: %s", i, exc)
507
+ continue
508
+
509
+ frame_mask = np.zeros((h, w), dtype=np.uint8)
510
+ for box in boxes:
511
+ cv2.fillPoly(frame_mask, [box.points.astype(np.int32)], 1)
512
+ freq += frame_mask
513
+ n_valid += 1
514
+
515
+ if n_valid == 0:
516
+ raise RuntimeError(
517
+ "Text detection failed on all sampled frames.\n"
518
+ "Provide a mask manually with -m, or check the detection model."
519
+ )
520
+
521
+ freq /= n_valid
522
+ mask = (freq >= consistency).astype(np.uint8)
523
+
524
+ # Morphological cleanup: dilate then close
525
+ kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (15, 5))
526
+ mask = cv2.dilate(mask, kernel, iterations=2)
527
+ mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
528
+
529
+ pct = 100.0 * mask.sum() / (h * w)
530
+ print(f"Auto-detected mask: {pct:.1f}% of frame area")
531
+
532
+ return mask[:, :, None]
533
+
534
+
535
+ _TIME_RE = re.compile(
536
+ r"(\b\d{1,2}:\d{2}(:\d{2})?\b|\b\d{4}[-/\.]\d{1,2}[-/\.]\d{1,2}\b)"
537
+ )
538
+ _WATERMARK_RE = re.compile(
539
+ r"(@|www\.|https?://|\.com\b|\.net\b|\.tv\b|tiktok|douyin|bilibili|youtube|weibo)",
540
+ re.IGNORECASE,
541
+ )
542
+ _INTENT_TARGETS = {
543
+ "subtitle": ("subtitle", "subtitles", "caption", "captions", "字幕"),
544
+ "timestamp": ("timestamp", "timecode", "date", "time", "时间戳", "日期", "时间"),
545
+ "watermark": ("watermark", "water mark", "水印", "账号", "网址"),
546
+ "logo": ("logo", "台标", "角标", "标志"),
547
+ "scene_text": ("scene text", "road sign", "sign", "路牌", "招牌", "画面文字"),
548
+ }
549
+ _INTENT_ZONES = {
550
+ "top-left": ("top left", "upper left", "左上", "左上角"),
551
+ "top-right": ("top right", "upper right", "右上", "右上角"),
552
+ "bottom-left": ("bottom left", "lower left", "左下", "���下角"),
553
+ "bottom-right": ("bottom right", "lower right", "右下", "右下角"),
554
+ "top": ("top", "upper", "顶部", "上方"),
555
+ "bottom": ("bottom", "lower", "底部", "下方"),
556
+ "center": ("center", "middle", "中间", "中央"),
557
+ }
558
+ _REGION_ALIASES = {
559
+ "top-left": ("top-left", "upper-left", "left-top", "左上", "左上角"),
560
+ "top-right": ("top-right", "upper-right", "right-top", "右上", "右上角"),
561
+ "bottom-left": ("bottom-left", "lower-left", "left-bottom", "左下", "左下角"),
562
+ "bottom-right": ("bottom-right", "lower-right", "right-bottom", "右下", "右下角"),
563
+ "top": ("top", "upper", "顶部", "上方"),
564
+ "bottom": ("bottom", "lower", "底部", "下方"),
565
+ "center": ("center", "middle", "中间", "中央"),
566
+ }
567
+ _KEEP_WORDS = ("keep", "preserve", "保留", "不要去", "别去", "别删", "不要删")
568
+ _REMOVE_WORDS = ("remove", "clean", "erase", "delete", "去掉", "清理", "删除", "擦掉")
569
+
570
+
571
+ def normalize_target(value: str) -> str:
572
+ """Normalize user-facing target names to candidate types."""
573
+ key = value.strip().lower().replace("-", "_").replace(" ", "_")
574
+ aliases = {
575
+ "sub": "subtitle",
576
+ "subs": "subtitle",
577
+ "caption": "subtitle",
578
+ "captions": "subtitle",
579
+ "text": "subtitle",
580
+ "subtitle": "subtitle",
581
+ "timestamp": "timestamp",
582
+ "time": "timestamp",
583
+ "date": "timestamp",
584
+ "watermark": "watermark",
585
+ "text_watermark": "watermark",
586
+ "logo": "logo",
587
+ "scene_text": "scene_text",
588
+ "unknown": "unknown_text",
589
+ "region": "region",
590
+ }
591
+ return aliases.get(key, key)
592
+
593
+
594
+ def normalize_region(value: str) -> str:
595
+ """Normalize user-facing region names."""
596
+ key = value.strip().lower().replace("_", "-").replace(" ", "-")
597
+ for region, aliases in _REGION_ALIASES.items():
598
+ if key in {alias.lower().replace("_", "-").replace(" ", "-") for alias in aliases}:
599
+ return region
600
+ return key
601
+
602
+
603
+ def infer_regions_from_text(text: str) -> list[str]:
604
+ """Infer region names mentioned in free-form text."""
605
+ regions = []
606
+ for region, aliases in _REGION_ALIASES.items():
607
+ if _mentions_any(text, aliases):
608
+ regions.append(region)
609
+ return regions
610
+
611
+
612
+ def infer_targets_from_text(text: str) -> list[str]:
613
+ """Infer target types mentioned in free-form text."""
614
+ return sorted(_mentioned_targets(text))
615
+
616
+
617
+ def _mentions_any(text: str, terms: Iterable[str]) -> bool:
618
+ folded = text.casefold()
619
+ return any(term.casefold() in folded for term in terms)
620
+
621
+
622
+ def _mentioned_targets(intent: str) -> set[str]:
623
+ return {
624
+ target
625
+ for target, terms in _INTENT_TARGETS.items()
626
+ if _mentions_any(intent, terms)
627
+ }
628
+
629
+
630
+ def _mentioned_zones(intent: str) -> set[str]:
631
+ zones = {
632
+ zone
633
+ for zone, terms in _INTENT_ZONES.items()
634
+ if _mentions_any(intent, terms)
635
+ }
636
+ if any(zone.startswith("top-") for zone in zones):
637
+ zones.add("top")
638
+ if any(zone.startswith("bottom-") for zone in zones):
639
+ zones.add("bottom")
640
+ return zones
641
+
642
+
643
+ def _mentioned_after_words(intent: str, words: Iterable[str]) -> tuple[set[str], set[str]]:
644
+ targets: set[str] = set()
645
+ zones: set[str] = set()
646
+ for word in words:
647
+ start = intent.casefold().find(word.casefold())
648
+ if start < 0:
649
+ continue
650
+ fragment = intent[start:start + 40]
651
+ for sep in (",", ";", ",", ";", "."):
652
+ fragment = fragment.split(sep, 1)[0]
653
+ targets.update(_mentioned_targets(fragment))
654
+ zones.update(_mentioned_zones(fragment))
655
+ return targets, zones
656
+
657
+
658
+ def _candidate_matches_intent(
659
+ candidate: CleanCandidate,
660
+ targets: set[str],
661
+ zones: set[str],
662
+ intent: str,
663
+ ) -> bool:
664
+ candidate_zone = candidate.label.split(" ", 1)[0]
665
+ if targets and normalize_target(candidate.type) not in targets:
666
+ return False
667
+ if zones:
668
+ zone_matches = candidate_zone in zones
669
+ if "top" in zones and candidate_zone.startswith("top"):
670
+ zone_matches = True
671
+ if "bottom" in zones and candidate_zone.startswith("bottom"):
672
+ zone_matches = True
673
+ if not zone_matches:
674
+ return False
675
+ samples = " ".join(candidate.text_samples).casefold()
676
+ return not samples or not intent or any(
677
+ sample.casefold() in intent.casefold()
678
+ for sample in candidate.text_samples
679
+ if sample
680
+ ) or bool(targets or zones)
681
+
682
+
683
+ def _bbox(points: np.ndarray, w: int, h: int) -> tuple[int, int, int, int]:
684
+ pts = points.astype(np.float32)
685
+ x1 = max(0, int(np.floor(pts[:, 0].min())))
686
+ y1 = max(0, int(np.floor(pts[:, 1].min())))
687
+ x2 = min(w - 1, int(np.ceil(pts[:, 0].max())))
688
+ y2 = min(h - 1, int(np.ceil(pts[:, 1].max())))
689
+ return x1, y1, x2, y2
690
+
691
+
692
+ def _zone(bbox: tuple[int, int, int, int], w: int, h: int) -> str:
693
+ x1, y1, x2, y2 = bbox
694
+ cx = (x1 + x2) / 2
695
+ cy = (y1 + y2) / 2
696
+ vertical = "top" if cy < h * 0.25 else "bottom" if cy > h * 0.68 else "middle"
697
+ horizontal = "left" if cx < w * 0.33 else "right" if cx > w * 0.67 else "center"
698
+ if vertical == "middle" and horizontal == "center":
699
+ return "center"
700
+ if vertical == "middle":
701
+ return horizontal
702
+ if horizontal == "center":
703
+ return vertical
704
+ return f"{vertical}-{horizontal}"
705
+
706
+
707
+
708
+ def _candidate_label(target_type: str, zone: str) -> str:
709
+ labels = {
710
+ "subtitle": "subtitle",
711
+ "timestamp": "timestamp",
712
+ "watermark": "text watermark",
713
+ "logo": "logo",
714
+ "scene_text": "scene text",
715
+ "unknown_text": "unknown text",
716
+ "region": "region",
717
+ }
718
+ return f"{zone} {labels.get(target_type, target_type)}"
719
+
720
+
721
+ def _region_bbox(region: str, w: int, h: int) -> tuple[int, int, int, int]:
722
+ band_h = max(1, int(h * 0.22))
723
+ band_w = max(1, int(w * 0.22))
724
+ center_w = max(1, int(w * 0.36))
725
+ center_h = max(1, int(h * 0.24))
726
+ boxes = {
727
+ "top-left": (0, 0, band_w - 1, band_h - 1),
728
+ "top-right": (w - band_w, 0, w - 1, band_h - 1),
729
+ "bottom-left": (0, h - band_h, band_w - 1, h - 1),
730
+ "bottom-right": (w - band_w, h - band_h, w - 1, h - 1),
731
+ "top": (0, 0, w - 1, band_h - 1),
732
+ "bottom": (0, h - band_h, w - 1, h - 1),
733
+ "center": (
734
+ (w - center_w) // 2,
735
+ (h - center_h) // 2,
736
+ (w + center_w) // 2,
737
+ (h + center_h) // 2,
738
+ ),
739
+ }
740
+ if region not in boxes:
741
+ raise ValueError(f"Unknown region: {region}")
742
+ return boxes[region]
743
+
744
+
745
+ def _mask_from_bbox(bbox: tuple[int, int, int, int], shape: tuple[int, int]) -> np.ndarray:
746
+ h, w = shape
747
+ x1, y1, x2, y2 = bbox
748
+ mask = np.zeros((h, w, 1), dtype=np.uint8)
749
+ mask[max(0, y1):min(h, y2 + 1), max(0, x1):min(w, x2 + 1), 0] = 1
750
+ return mask
751
+
752
+
753
+ def _region_candidates(
754
+ regions: Iterable[str],
755
+ shape: tuple[int, int],
756
+ start_index: int = 1,
757
+ ) -> list[CleanCandidate]:
758
+ h, w = shape
759
+ candidates: list[CleanCandidate] = []
760
+ for offset, raw_region in enumerate(regions):
761
+ region = normalize_region(raw_region)
762
+ bbox = _region_bbox(region, w, h)
763
+ candidates.append(
764
+ CleanCandidate(
765
+ id=f"r{start_index + offset}",
766
+ type="region",
767
+ label=f"{region} region",
768
+ bbox=bbox,
769
+ confidence=1.0,
770
+ frame_fraction=1.0,
771
+ reason=f"user-specified {region} region",
772
+ default_remove=True,
773
+ mask=_mask_from_bbox(bbox, shape),
774
+ )
775
+ )
776
+ return candidates
777
+
778
+
779
+ def _largest_overlay_candidate(
780
+ mask: np.ndarray,
781
+ zone: str,
782
+ target_type: str,
783
+ reason: str,
784
+ shape: tuple[int, int],
785
+ candidate_id: str,
786
+ confidence: float,
787
+ ) -> CleanCandidate | None:
788
+ h, w = shape
789
+ contours, _ = cv2.findContours(mask.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
790
+ if not contours:
791
+ return None
792
+ contour = max(contours, key=cv2.contourArea)
793
+ area = cv2.contourArea(contour)
794
+ if area < max(12, h * w * 0.0005):
795
+ return None
796
+ x, y, bw, bh = cv2.boundingRect(contour)
797
+ if bw > w * 0.55 or bh > h * 0.35:
798
+ return None
799
+ bbox = (x, y, x + bw - 1, y + bh - 1)
800
+ dilated = cv2.dilate(mask.astype(np.uint8), cv2.getStructuringElement(cv2.MORPH_RECT, (7, 7)), iterations=1)
801
+ return CleanCandidate(
802
+ id=candidate_id,
803
+ type=target_type, # type: ignore[arg-type]
804
+ label=_candidate_label(target_type, zone),
805
+ bbox=bbox,
806
+ confidence=confidence,
807
+ frame_fraction=1.0,
808
+ reason=reason,
809
+ default_remove=False,
810
+ mask=dilated[:, :, None],
811
+ )
812
+
813
+
814
+ def _prepare_band_variant(crop: np.ndarray, variant: str) -> np.ndarray:
815
+ """Prepare an image variant for band fallback detection."""
816
+ if variant == "original":
817
+ return crop
818
+ if variant == "contrast":
819
+ gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)
820
+ clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
821
+ enhanced = clahe.apply(gray)
822
+ return cv2.cvtColor(enhanced, cv2.COLOR_GRAY2BGR)
823
+ if variant == "inverted":
824
+ return cv2.bitwise_not(crop)
825
+ return crop
826
+
827
+
828
+ def _iou_bbox(
829
+ bbox1: tuple[int, int, int, int],
830
+ bbox2: tuple[int, int, int, int],
831
+ ) -> float:
832
+ """Compute IoU between two axis-aligned bounding boxes."""
833
+ x1 = max(bbox1[0], bbox2[0])
834
+ y1 = max(bbox1[1], bbox2[1])
835
+ x2 = min(bbox1[2], bbox2[2])
836
+ y2 = min(bbox1[3], bbox2[3])
837
+ inter = max(0, x2 - x1 + 1) * max(0, y2 - y1 + 1)
838
+ area1 = (bbox1[2] - bbox1[0] + 1) * (bbox1[3] - bbox1[1] + 1)
839
+ area2 = (bbox2[2] - bbox2[0] + 1) * (bbox2[3] - bbox2[1] + 1)
840
+ union = area1 + area2 - inter
841
+ return inter / union if union > 0 else 0.0
842
+
843
+
844
+ def _box_overlaps_bbox(
845
+ box: TextBox, bbox: tuple[int, int, int, int], width: int, height: int,
846
+ ) -> bool:
847
+ """Whether a detector box intersects a candidate bbox."""
848
+ bx1, by1, bx2, by2 = _bbox(box.points, width, height)
849
+ x1, y1, x2, y2 = bbox
850
+ return bx1 <= x2 and bx2 >= x1 and by1 <= y2 and by2 >= y1
851
+
852
+
853
+ def _band_fallback_detect(
854
+ frames: list[np.ndarray],
855
+ detector: TextDetector,
856
+ mode: str = "light",
857
+ consistency: float = 0.4,
858
+ ) -> list[CleanCandidate]:
859
+ """Detect text in subtitle bands missed by the main frequency-map pass.
860
+
861
+ For each band (bottom 40%, optionally top 25%), creates image variants
862
+ and runs the detector. Builds a per-pixel frequency map from fallback
863
+ detections, then extracts connected-component candidates.
864
+ """
865
+ if not frames:
866
+ return []
867
+
868
+ h, w = frames[0].shape[:2]
869
+
870
+ bands: list[tuple[str, int, int, int, int]] = []
871
+ bands.append(("bottom", 0, int(h * 0.6), w - 1, h - 1))
872
+ if mode == "force":
873
+ bands.append(("top", 0, 0, w - 1, max(0, int(h * 0.25) - 1)))
874
+
875
+ if mode == "light":
876
+ variants = ["original", "contrast"]
877
+ else:
878
+ variants = ["original", "contrast", "inverted"]
879
+
880
+ freq = np.zeros((h, w), dtype=np.float32)
881
+ n_valid = 0
882
+
883
+ for frame in frames:
884
+ frame_mask = np.zeros((h, w), dtype=np.uint8)
885
+ for _band_name, bx1, by1, bx2, by2 in bands:
886
+ crop = frame[by1:by2 + 1, bx1:bx2 + 1]
887
+ if crop.size == 0:
888
+ continue
889
+ for variant in variants:
890
+ prepared = _prepare_band_variant(crop, variant)
891
+ try:
892
+ boxes = detector.detect(prepared)
893
+ except Exception:
894
+ continue
895
+ for box in boxes:
896
+ pts = box.points.copy()
897
+ pts[:, 0] += bx1
898
+ pts[:, 1] += by1
899
+ cv2.fillPoly(frame_mask, [pts.astype(np.int32)], 1)
900
+ freq += frame_mask
901
+ n_valid += 1
902
+
903
+ if n_valid == 0:
904
+ return []
905
+
906
+ freq /= n_valid
907
+
908
+ text_mask = (freq >= consistency).astype(np.uint8)
909
+ kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (15, 5))
910
+ text_mask = cv2.dilate(text_mask, kernel, iterations=2)
911
+ text_mask = cv2.morphologyEx(text_mask, cv2.MORPH_CLOSE, kernel)
912
+
913
+ num_labels, labels = cv2.connectedComponents(text_mask)
914
+
915
+ candidates: list[CleanCandidate] = []
916
+ for label_id in range(1, num_labels):
917
+ component = (labels == label_id).astype(np.uint8)
918
+ ys, xs = np.where(component > 0)
919
+ if len(xs) < 10:
920
+ continue
921
+ x1, y1, x2, y2 = int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())
922
+
923
+ zone = _zone((x1, y1, x2, y2), w, h)
924
+ target_type, reason, default_remove = _classify_region(
925
+ (x1, y1, x2, y2), zone, [], w, h,
926
+ )
927
+
928
+ region_freq = freq[y1:y2 + 1, x1:x2 + 1]
929
+ pos_freq = region_freq[region_freq > 0]
930
+ confidence = float(pos_freq.mean()) if len(pos_freq) > 0 else 0.0
931
+ frame_fraction = float(region_freq.mean())
932
+
933
+ component_mask = (labels[y1:y2 + 1, x1:x2 + 1] == label_id).astype(np.uint8)
934
+ full_mask = np.zeros((h, w, 1), dtype=np.uint8)
935
+ full_mask[y1:y2 + 1, x1:x2 + 1, 0] = component_mask
936
+
937
+ candidates.append(
938
+ CleanCandidate(
939
+ id=f"b{len(candidates) + 1}",
940
+ type=target_type, # type: ignore[arg-type]
941
+ label=_candidate_label(target_type, zone),
942
+ bbox=(x1, y1, x2, y2),
943
+ confidence=confidence,
944
+ frame_fraction=frame_fraction,
945
+ reason=f"band fallback: {reason}",
946
+ default_remove=default_remove,
947
+ mask=full_mask,
948
+ )
949
+ )
950
+
951
+ return candidates
952
+
953
+
954
+ def _detect_fixed_logo_candidates(
955
+ frames: list[np.ndarray],
956
+ start_index: int = 1,
957
+ ) -> list[CleanCandidate]:
958
+ if len(frames) < 2:
959
+ return []
960
+ h, w = frames[0].shape[:2]
961
+ zones = ["top-left", "top-right", "bottom-left", "bottom-right"]
962
+ candidates: list[CleanCandidate] = []
963
+ first_gray = cv2.cvtColor(frames[0], cv2.COLOR_BGR2GRAY)
964
+ edge = cv2.Canny(first_gray, 40, 120)
965
+
966
+ for zone in zones:
967
+ x1, y1, x2, y2 = _region_bbox(zone, w, h)
968
+ zone_mask = np.zeros((h, w), dtype=np.uint8)
969
+ crop = edge[y1:y2 + 1, x1:x2 + 1]
970
+ if crop.mean() < 1.5:
971
+ continue
972
+ zone_mask[y1:y2 + 1, x1:x2 + 1] = crop > 0
973
+
974
+ stable = True
975
+ for frame in frames[1:min(len(frames), 6)]:
976
+ gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
977
+ next_crop = cv2.Canny(gray, 40, 120)[y1:y2 + 1, x1:x2 + 1] > 0
978
+ base = crop > 0
979
+ union = np.logical_or(base, next_crop).sum()
980
+ overlap = np.logical_and(base, next_crop).sum()
981
+ if union and overlap / union < 0.45:
982
+ stable = False
983
+ break
984
+ if not stable:
985
+ continue
986
+
987
+ zone_mask = cv2.dilate(
988
+ zone_mask,
989
+ cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3)),
990
+ iterations=1,
991
+ )
992
+ candidate = _largest_overlay_candidate(
993
+ zone_mask,
994
+ zone,
995
+ "logo",
996
+ f"fixed edge graphic in {zone}",
997
+ (h, w),
998
+ f"l{start_index + len(candidates)}",
999
+ confidence=0.55,
1000
+ )
1001
+ if candidate is not None:
1002
+ candidates.append(candidate)
1003
+ return candidates
1004
+
1005
+
1006
+ def _detect_translucent_watermark_candidates(
1007
+ frames: list[np.ndarray],
1008
+ start_index: int = 1,
1009
+ ) -> list[CleanCandidate]:
1010
+ if not frames:
1011
+ return []
1012
+ h, w = frames[0].shape[:2]
1013
+ gray = cv2.cvtColor(frames[0], cv2.COLOR_BGR2GRAY)
1014
+ blur = cv2.GaussianBlur(gray, (0, 0), 7)
1015
+ contrast = cv2.absdiff(gray, blur)
1016
+ soft = ((contrast > 5) & (contrast < 45)).astype(np.uint8)
1017
+ x1, y1, x2, y2 = _region_bbox("center", w, h)
1018
+ mask = np.zeros((h, w), dtype=np.uint8)
1019
+ mask[y1:y2 + 1, x1:x2 + 1] = soft[y1:y2 + 1, x1:x2 + 1]
1020
+ mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, cv2.getStructuringElement(cv2.MORPH_RECT, (9, 3)))
1021
+
1022
+ candidate = _largest_overlay_candidate(
1023
+ mask,
1024
+ "center",
1025
+ "watermark",
1026
+ "possible translucent center watermark",
1027
+ (h, w),
1028
+ f"w{start_index}",
1029
+ confidence=0.45,
1030
+ )
1031
+ return [candidate] if candidate is not None else []
1032
+
1033
+
1034
+ def _classify_region(
1035
+ bbox: tuple[int, int, int, int],
1036
+ zone: str,
1037
+ text_samples: list[str],
1038
+ w: int,
1039
+ h: int,
1040
+ ) -> tuple[str, str, bool]:
1041
+ """Classify a detected region by position and content patterns."""
1042
+ x1, y1, x2, y2 = bbox
1043
+ bw = max(1, x2 - x1)
1044
+ bh = max(1, y2 - y1)
1045
+ cy = (y1 + y2) / 2
1046
+ width_ratio = bw / float(w)
1047
+ area_ratio = (bw * bh) / float(w * h)
1048
+ text = " ".join(text_samples).strip()
1049
+
1050
+ if text and _TIME_RE.search(text):
1051
+ return "timestamp", f"time-like text in {zone}", True
1052
+ if text and _WATERMARK_RE.search(text):
1053
+ return "watermark", f"watermark-like text in {zone}", True
1054
+
1055
+ height_ratio = bh / float(h)
1056
+
1057
+ if cy > h * 0.50 and width_ratio > 0.15:
1058
+ return "subtitle", f"wide bottom text in {zone}", True
1059
+ if cy < h * 0.30 and width_ratio > 0.15:
1060
+ return "subtitle", f"wide top text in {zone}", True
1061
+
1062
+ # Wide thin text strip below top 25% → likely subtitle regardless of vertical position
1063
+ if width_ratio > 0.40 and height_ratio < 0.08 and cy > h * 0.25:
1064
+ return "subtitle", f"wide thin text in {zone}", True
1065
+
1066
+ edge = x1 < w * 0.12 or x2 > w * 0.88 or y1 < h * 0.18 or y2 > h * 0.80
1067
+ if edge and area_ratio < 0.05:
1068
+ return "watermark", f"small persistent edge text in {zone}", True
1069
+
1070
+ return "scene_text", f"text in {zone}", False
1071
+
1072
+
1073
+ DETECT_MODES: dict[str, dict] = {
1074
+ "fast": {
1075
+ "sample_count": 24,
1076
+ "consistency": 0.50,
1077
+ "subtitle_fallback": "off",
1078
+ },
1079
+ "balanced": {
1080
+ "sample_count": 50,
1081
+ "consistency": 0.40,
1082
+ "subtitle_fallback": "light",
1083
+ },
1084
+ "sensitive": {
1085
+ "sample_count": 80,
1086
+ "consistency": 0.30,
1087
+ "subtitle_fallback": "force",
1088
+ },
1089
+ }
1090
+
1091
+
1092
+ def resolve_detect_params(
1093
+ mode: str,
1094
+ has_subtitle_target: bool = False,
1095
+ ) -> dict:
1096
+ """Resolve a detect-mode name into concrete detection parameters.
1097
+
1098
+ Returns a dict with keys ``sample_count``, ``consistency``, and
1099
+ ``subtitle_fallback``.
1100
+
1101
+ When *has_subtitle_target* is ``True``, ``subtitle_fallback`` is
1102
+ upgraded to ``"force"`` regardless of mode, because an explicit subtitle
1103
+ request signals that subtitle recall matters more than speed.
1104
+ """
1105
+ if mode not in DETECT_MODES:
1106
+ raise ValueError(
1107
+ f"Unknown detect mode: {mode!r}. Choose from: {list(DETECT_MODES)}"
1108
+ )
1109
+ params = dict(DETECT_MODES[mode])
1110
+ if has_subtitle_target:
1111
+ params["subtitle_fallback"] = "force"
1112
+ return params
1113
+
1114
+
1115
+ def detect_clean_candidates(
1116
+ video_path: str,
1117
+ detector: TextDetector | None = None,
1118
+ sample_count: int = 50,
1119
+ regions: Iterable[str] | None = None,
1120
+ detect_text: bool = True,
1121
+ include_logo: bool = False,
1122
+ include_translucent_watermark: bool = False,
1123
+ consistency: float = 0.4,
1124
+ subtitle_fallback: str = "off",
1125
+ recognizer: object | None = None,
1126
+ ) -> CleanDetectionResult:
1127
+ """Detect removable clean targets from sampled video frames.
1128
+
1129
+ Uses a frequency-map approach: builds a per-pixel frequency map of
1130
+ text detections across sampled frames, then finds connected regions
1131
+ and classifies each by position and content.
1132
+
1133
+ Args:
1134
+ recognizer: Optional callable ``(image_crop) -> str | None``.
1135
+ When provided and a detected text box has no ``.text`` field,
1136
+ the crop is passed to *recognizer* to fill ``text_samples``.
1137
+ """
1138
+ if detect_text and detector is None:
1139
+ detector = _default_detector()
1140
+
1141
+ indexed = _sample_frames_with_indices(video_path, sample_count)
1142
+ if not indexed:
1143
+ raise ValueError(f"No frames could be read from: {video_path}")
1144
+
1145
+ all_sample_indices = [idx for idx, _ in indexed]
1146
+ frames = [frame for _, frame in indexed]
1147
+ h, w = frames[0].shape[:2]
1148
+ candidates: list[CleanCandidate] = []
1149
+ n_valid = 0
1150
+ valid_sample_indices: list[int] = []
1151
+
1152
+ if detect_text and detector is not None:
1153
+ freq = np.zeros((h, w), dtype=np.float32)
1154
+ all_frame_boxes: list[list[TextBox]] = []
1155
+ best_preview_idx = 0
1156
+ best_preview_score = -1
1157
+
1158
+ for i, frame in enumerate(frames):
1159
+ try:
1160
+ boxes = detector.detect(frame)
1161
+ except Exception as exc:
1162
+ logger.warning("Clean detection failed on sampled frame: %s", exc)
1163
+ continue
1164
+ n_valid += 1
1165
+ all_frame_boxes.append(boxes)
1166
+ valid_sample_indices.append(all_sample_indices[i])
1167
+ frame_mask = np.zeros((h, w), dtype=np.uint8)
1168
+ for box in boxes:
1169
+ cv2.fillPoly(frame_mask, [box.points.astype(np.int32)], 1)
1170
+ freq += frame_mask
1171
+
1172
+ score = int(frame_mask.sum())
1173
+ if score > best_preview_score:
1174
+ best_preview_score = score
1175
+ best_preview_idx = i
1176
+
1177
+ if n_valid == 0:
1178
+ raise RuntimeError("Target detection failed on all sampled frames.")
1179
+
1180
+ freq /= n_valid
1181
+
1182
+ text_mask = (freq >= consistency).astype(np.uint8)
1183
+ kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (15, 5))
1184
+ text_mask = cv2.dilate(text_mask, kernel, iterations=2)
1185
+ text_mask = cv2.morphologyEx(text_mask, cv2.MORPH_CLOSE, kernel)
1186
+
1187
+ num_labels, labels = cv2.connectedComponents(text_mask)
1188
+
1189
+ raw_regions: list[tuple[int, int, int, int, int]] = [] # (label_id, x1, y1, x2, y2)
1190
+ for label_id in range(1, num_labels):
1191
+ component = (labels == label_id).astype(np.uint8)
1192
+ ys, xs = np.where(component > 0)
1193
+ if len(xs) < 10:
1194
+ continue
1195
+ raw_regions.append((label_id, int(xs.min()), int(ys.min()), int(xs.max()), int(ys.max())))
1196
+
1197
+ raw_regions.sort(key=lambda b: (b[2], b[1]))
1198
+
1199
+ for label_id, x1, y1, x2, y2 in raw_regions:
1200
+ text_samples: list[str] = []
1201
+ ocr_crops: list[np.ndarray] = []
1202
+ presence_frames: list[int] = []
1203
+ for sample_pos, boxes in enumerate(all_frame_boxes):
1204
+ overlapped = False
1205
+ for box in boxes:
1206
+ if _box_overlaps_bbox(box, (x1, y1, x2, y2), w, h):
1207
+ overlapped = True
1208
+ bx1, by1, bx2, by2 = _bbox(box.points, w, h)
1209
+ if box.text:
1210
+ text_samples.append(box.text)
1211
+ elif recognizer is not None:
1212
+ crop = frames[0][by1:by2 + 1, bx1:bx2 + 1]
1213
+ if crop.size > 0:
1214
+ ocr_crops.append(crop)
1215
+ if overlapped:
1216
+ presence_frames.append(valid_sample_indices[sample_pos])
1217
+
1218
+ if not text_samples and ocr_crops and recognizer is not None:
1219
+ for crop in ocr_crops[:3]:
1220
+ try:
1221
+ text = recognizer(crop)
1222
+ except Exception:
1223
+ text = None
1224
+ if text:
1225
+ text_samples.append(text)
1226
+
1227
+ zone = _zone((x1, y1, x2, y2), w, h)
1228
+ target_type, reason, default_remove = _classify_region(
1229
+ (x1, y1, x2, y2), zone, text_samples, w, h,
1230
+ )
1231
+
1232
+ region_freq = freq[y1:y2 + 1, x1:x2 + 1]
1233
+ pos_freq = region_freq[region_freq > 0]
1234
+ confidence = float(pos_freq.mean()) if len(pos_freq) > 0 else 0.0
1235
+ frame_fraction = float(region_freq.mean())
1236
+
1237
+ component_mask = (labels[y1:y2 + 1, x1:x2 + 1] == label_id).astype(np.uint8)
1238
+ full_mask = np.zeros((h, w, 1), dtype=np.uint8)
1239
+ full_mask[y1:y2 + 1, x1:x2 + 1, 0] = component_mask
1240
+
1241
+ candidates.append(
1242
+ CleanCandidate(
1243
+ id=f"c{len(candidates) + 1}",
1244
+ type=target_type, # type: ignore[arg-type]
1245
+ label=_candidate_label(target_type, zone),
1246
+ bbox=(x1, y1, x2, y2),
1247
+ confidence=confidence,
1248
+ frame_fraction=frame_fraction,
1249
+ reason=reason,
1250
+ default_remove=default_remove,
1251
+ text_samples=sorted(set(text_samples))[:5],
1252
+ presence_frames=presence_frames,
1253
+ mask=full_mask,
1254
+ detector_backed=True,
1255
+ )
1256
+ )
1257
+
1258
+ if subtitle_fallback != "off" and detect_text and detector is not None:
1259
+ fallback_raw = _band_fallback_detect(
1260
+ frames, detector, mode=subtitle_fallback, consistency=consistency,
1261
+ )
1262
+ main_bboxes = [c.bbox for c in candidates]
1263
+ surviving = [
1264
+ fc for fc in fallback_raw
1265
+ if not any(_iou_bbox(fc.bbox, mb) > 0.3 for mb in main_bboxes)
1266
+ ]
1267
+ for idx, fc in enumerate(surviving, 1):
1268
+ fc.id = f"b{idx}"
1269
+ candidates.append(fc)
1270
+
1271
+ next_index = len(candidates) + 1
1272
+ if regions:
1273
+ candidates.extend(_region_candidates(regions, (h, w), start_index=next_index))
1274
+ next_index = len(candidates) + 1
1275
+ if include_logo:
1276
+ candidates.extend(_detect_fixed_logo_candidates(frames, start_index=next_index))
1277
+ next_index = len(candidates) + 1
1278
+ if include_translucent_watermark:
1279
+ candidates.extend(
1280
+ _detect_translucent_watermark_candidates(frames, start_index=next_index)
1281
+ )
1282
+
1283
+ return CleanDetectionResult(
1284
+ candidates=candidates,
1285
+ frame_shape=(h, w),
1286
+ sample_indices=valid_sample_indices,
1287
+ preview_frame=frames[best_preview_idx].copy() if detect_text and detector is not None else frames[0].copy(),
1288
+ detector=detector,
1289
+ )
1290
+
1291
+
1292
+ def refine_temporal_presence(
1293
+ video_path: str,
1294
+ result: CleanDetectionResult,
1295
+ candidate_segments: dict[str, Iterable[object]],
1296
+ expected_frame_count: int,
1297
+ progress=None,
1298
+ check_cancelled=None,
1299
+ ) -> list[str]:
1300
+ """Densely recheck detector-backed remove candidates inside coarse segments.
1301
+
1302
+ Detection remains sequential and each active video frame is passed to the
1303
+ detector once. A detector error is negative evidence: keeping that frame
1304
+ is safer than carrying forward a coarse remove decision.
1305
+ """
1306
+ detector = result.detector
1307
+ candidates = {
1308
+ candidate.id: candidate
1309
+ for candidate in result.candidates
1310
+ if candidate.id in candidate_segments and getattr(
1311
+ candidate, "detector_backed", bool(candidate.presence_frames)
1312
+ )
1313
+ }
1314
+ if detector is None or not candidates:
1315
+ return []
1316
+
1317
+ segments = {
1318
+ candidate_id: [
1319
+ (int(segment.start), int(segment.end))
1320
+ for segment in candidate_segments[candidate_id]
1321
+ ]
1322
+ for candidate_id in candidates
1323
+ }
1324
+ cap = cv2.VideoCapture(video_path)
1325
+ if not cap.isOpened():
1326
+ raise ValueError(f"Cannot open video for temporal refinement: {video_path}")
1327
+
1328
+ warnings: list[str] = []
1329
+ try:
1330
+ frame_index = 0
1331
+ while frame_index < expected_frame_count:
1332
+ if check_cancelled is not None:
1333
+ check_cancelled()
1334
+ ok, frame = cap.read()
1335
+ if not ok:
1336
+ raise ValueError(
1337
+ f"Temporal refinement decoded {frame_index} frames; "
1338
+ f"expected {expected_frame_count}"
1339
+ )
1340
+ active = [
1341
+ candidate
1342
+ for candidate_id, candidate in candidates.items()
1343
+ if any(start <= frame_index < end for start, end in segments[candidate_id])
1344
+ ]
1345
+ if active:
1346
+ for candidate in active:
1347
+ candidate.temporal_sample_indices = sorted(set(
1348
+ candidate.temporal_sample_indices or result.sample_indices
1349
+ ) | {frame_index})
1350
+ candidate.presence_frames = [
1351
+ index for index in candidate.presence_frames if index != frame_index
1352
+ ]
1353
+ try:
1354
+ boxes = detector.detect(frame)
1355
+ except Exception as exc: # safety boundary: failed frame remains keep.
1356
+ warnings.append(
1357
+ f"temporal refinement failed at frame {frame_index}; keeping frame: {exc}"
1358
+ )
1359
+ else:
1360
+ for candidate in active:
1361
+ if any(
1362
+ _box_overlaps_bbox(box, candidate.bbox, frame.shape[1], frame.shape[0])
1363
+ for box in boxes
1364
+ ):
1365
+ candidate.presence_frames.append(frame_index)
1366
+ frame_index += 1
1367
+ if progress is not None:
1368
+ progress(frame_index, expected_frame_count)
1369
+ finally:
1370
+ cap.release()
1371
+
1372
+ for candidate in candidates.values():
1373
+ candidate.presence_frames = sorted(set(candidate.presence_frames))
1374
+ return warnings
1375
+
1376
+
1377
+ def select_clean_candidates(
1378
+ candidates: Iterable[CleanCandidate],
1379
+ targets: Iterable[str] | None = None,
1380
+ intent: str | None = None,
1381
+ ) -> list[CleanCandidate]:
1382
+ """Select candidates for removal by default rules or requested targets."""
1383
+ candidate_list = list(candidates)
1384
+ normalized = {normalize_target(t) for t in (targets or []) if t}
1385
+ if not normalized:
1386
+ selected = [c for c in candidate_list if c.default_remove]
1387
+ else:
1388
+ selected = [c for c in candidate_list if normalize_target(c.type) in normalized]
1389
+ if intent:
1390
+ selected = select_candidates_by_intent(candidate_list, intent, selected)
1391
+ return selected
1392
+
1393
+
1394
+ def select_candidates_by_intent(
1395
+ candidates: Iterable[CleanCandidate],
1396
+ intent: str,
1397
+ fallback: Iterable[CleanCandidate] | None = None,
1398
+ ) -> list[CleanCandidate]:
1399
+ """Select candidates using conservative local intent rules."""
1400
+ candidate_list = list(candidates)
1401
+ keep_mode = _mentions_any(intent, _KEEP_WORDS)
1402
+ remove_mode = _mentions_any(intent, _REMOVE_WORDS)
1403
+ targets = _mentioned_targets(intent)
1404
+ zones = _mentioned_zones(intent)
1405
+ fallback_list = list(fallback or [])
1406
+
1407
+ if keep_mode and not remove_mode:
1408
+ keep_targets = targets
1409
+ keep_zones = zones
1410
+ return [
1411
+ c for c in fallback_list
1412
+ if not _candidate_matches_intent(c, keep_targets, keep_zones, intent)
1413
+ ]
1414
+
1415
+ keep_targets, keep_zones = _mentioned_after_words(intent, _KEEP_WORDS)
1416
+ remove_targets, remove_zones = _mentioned_after_words(intent, _REMOVE_WORDS)
1417
+ if keep_mode and remove_mode:
1418
+ targets = remove_targets or (targets - keep_targets)
1419
+ zones = remove_zones or zones
1420
+
1421
+ if not targets and not zones:
1422
+ return fallback_list
1423
+
1424
+ selected = [
1425
+ c for c in candidate_list
1426
+ if _candidate_matches_intent(c, targets, zones, intent)
1427
+ ]
1428
+ if keep_targets or keep_zones:
1429
+ selected = [
1430
+ c for c in selected
1431
+ if not _candidate_matches_intent(c, keep_targets, keep_zones, intent)
1432
+ ]
1433
+ return selected
1434
+
1435
+
1436
+ def mask_from_candidates(
1437
+ candidates: Iterable[CleanCandidate],
1438
+ frame_shape: tuple[int, int],
1439
+ feather_radius: int = 0,
1440
+ ) -> np.ndarray:
1441
+ """Merge candidate masks into the mask format used by inpainting tasks.
1442
+
1443
+ Candidates are merged first (``np.maximum``). When ``feather_radius > 0``,
1444
+ the *merged* mask's outer boundary is then blurred with a Gaussian so the
1445
+ inpainting blend produces a soft seam instead of a hard edge. The interior
1446
+ (mask >= 1.0) is pinned back to full opacity so thin candidates (e.g. a
1447
+ 4-pixel-tall subtitle band) are not eroded inward.
1448
+
1449
+ Earlier revisions feathered each bbox-only candidate independently. That
1450
+ was a no-op in practice because the clean-task detector emits a full-image
1451
+ ``mask`` for every candidate, so the bbox-only branch never ran. Feathering
1452
+ the final merged mask fixes this and also softens seams around candidates
1453
+ whose detector-provided mask already has a hard edge.
1454
+
1455
+ Output dtype is ``float32`` with values in ``[0, 1]`` when
1456
+ ``feather_radius > 0``, and ``uint8`` with values in ``{0, 1}`` when
1457
+ ``feather_radius == 0`` (backwards-compatible with the eval IoU path,
1458
+ which compares against binary ground-truth masks).
1459
+ """
1460
+ h, w = frame_shape
1461
+ # Always merge candidates as float32 internally; cast down to uint8 only
1462
+ # for the legacy binary path at the end.
1463
+ mask = np.zeros((h, w, 1), dtype=np.float32)
1464
+ for candidate in candidates:
1465
+ if candidate.mask is not None:
1466
+ mask = np.maximum(mask, candidate.mask.astype(np.float32))
1467
+ continue
1468
+ x1, y1, x2, y2 = candidate.bbox
1469
+ mask[y1:y2 + 1, x1:x2 + 1, 0] = 1.0
1470
+
1471
+ if feather_radius > 0:
1472
+ # Feather the OUTER boundary of the merged mask: blur it, then pin
1473
+ # the original interior (mask >= 1.0) back to full opacity so the
1474
+ # filled region's core stays 1.0 and only the edge gets a soft
1475
+ # falloff into the surrounding frame.
1476
+ flat = mask[:, :, 0]
1477
+ k = max(3, feather_radius * 2 + 1)
1478
+ blurred = cv2.GaussianBlur(flat, (k, k), feather_radius / 2.0)
1479
+ flat = np.where(flat >= 1.0, 1.0, blurred)
1480
+ return np.clip(flat[:, :, None], 0.0, 1.0)
1481
+
1482
+ return np.clip(mask, 0, 1).astype(np.uint8)
1483
+
1484
+
1485
+ def write_clean_artifacts(
1486
+ result: CleanDetectionResult,
1487
+ selected: Iterable[CleanCandidate],
1488
+ output_dir: str,
1489
+ ) -> dict[str, str]:
1490
+ """Write candidate JSON and preview image artifacts."""
1491
+ os.makedirs(output_dir, exist_ok=True)
1492
+ selected_ids = {c.id for c in selected}
1493
+ candidates_path = os.path.join(output_dir, "clean_candidates.json")
1494
+ with open(candidates_path, "w", encoding="utf-8") as fh:
1495
+ json.dump(
1496
+ {
1497
+ "candidates": [
1498
+ {
1499
+ **candidate.to_dict(),
1500
+ "selected": candidate.id in selected_ids,
1501
+ }
1502
+ for candidate in result.candidates
1503
+ ]
1504
+ },
1505
+ fh,
1506
+ indent=2,
1507
+ ensure_ascii=False,
1508
+ )
1509
+
1510
+ preview_path = os.path.join(output_dir, "clean_preview.jpg")
1511
+ if result.preview_frame is not None:
1512
+ preview = result.preview_frame.copy()
1513
+ for candidate in result.candidates:
1514
+ x1, y1, x2, y2 = candidate.bbox
1515
+ color = (0, 200, 0) if candidate.id in selected_ids else (0, 165, 255)
1516
+ cv2.rectangle(preview, (x1, y1), (x2, y2), color, 2)
1517
+ cv2.putText(
1518
+ preview,
1519
+ f"{candidate.id}:{candidate.type}",
1520
+ (x1, max(16, y1 - 6)),
1521
+ cv2.FONT_HERSHEY_SIMPLEX,
1522
+ 0.5,
1523
+ color,
1524
+ 1,
1525
+ cv2.LINE_AA,
1526
+ )
1527
+ if not cv2.imwrite(preview_path, preview):
1528
+ raise OSError(f"Failed to write image: {preview_path}")
1529
+
1530
+ return {"candidates": candidates_path, "preview": preview_path}
1531
+
1532
+
1533
+ def _default_detector() -> DBNetDetector:
1534
+ """Create the default detector with auto-downloaded weights."""
1535
+ from videoclean.weights import ensure_weight
1536
+
1537
+ weight = ensure_weight("ppocrv5_det_mob.onnx", version="v0.1.0")
1538
+ return DBNetDetector(weight)
src/videoclean/engine.py ADDED
@@ -0,0 +1,362 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Focused OpenCV video-cleaning engine."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import os
6
+ import shutil
7
+ import threading
8
+ import time
9
+ from typing import TYPE_CHECKING, Optional
10
+
11
+ import cv2
12
+ import numpy as np
13
+
14
+ from videoclean.api import CancellationToken, ProgressCallback, ProgressEvent, WipeRequest, WipeResult
15
+ from videoclean.errors import InvalidInputError, ProcessingCancelledError, ProcessingError, WipeError
16
+ from videoclean.inpainters import get_registry, InpaintJob
17
+ from videoclean.plan import (
18
+ WipePlan, build_refined_wipe_plan, compute_source, is_temporal,
19
+ load_wipe_plan, save_wipe_plan, validate_plan,
20
+ )
21
+ from videoclean.tasks.base import BaseTask, read_frame_info, read_mask, validate_mask_shape
22
+ from videoclean.tasks.detext import DetextTask
23
+
24
+ if TYPE_CHECKING:
25
+ from videoclean.detect import TextDetector
26
+
27
+ _TASK_CLASSES = {"detext": DetextTask, "clean": DetextTask}
28
+ _DEFAULT_FEATHER_RADIUS = 4
29
+
30
+
31
+ class _ProgressCallbackError(Exception):
32
+ def __init__(self, cause: Exception) -> None:
33
+ super().__init__(str(cause))
34
+ self.cause = cause
35
+
36
+
37
+ class WipeEngine:
38
+ """Reusable engine for deterministic, fixed-mask OpenCV inpainting."""
39
+
40
+ def __init__(
41
+ self, task: str = "detext", *, verbose: bool = False, gap: int = 10,
42
+ dual: bool = False, detector: Optional[TextDetector] = None,
43
+ model: str = "opencv", model_options: Optional[dict] = None,
44
+ detect_mode: str = "balanced", ocr: str = "auto", **legacy,
45
+ ):
46
+ if task not in _TASK_CLASSES:
47
+ raise ValueError(f"Unknown task: {task}. Choose from: {list(_TASK_CLASSES)}")
48
+ if model != "opencv":
49
+ raise ValueError("videoclean supports only the OpenCV inpainter")
50
+ self.task = task
51
+ self._verbose = verbose
52
+ self._detector = detector
53
+ self._detect_mode = detect_mode
54
+ self._ocr = ocr
55
+ self._model_options = dict(model_options or {})
56
+ self._task_impl: BaseTask = _TASK_CLASSES[task](gap=gap, dual=dual)
57
+ self._task_impl.inpainter = get_registry().create("opencv", **self._model_options)
58
+ self._task_impl.backend = self._task_impl.inpainter
59
+ self._task_impl.feather_radius = _DEFAULT_FEATHER_RADIUS
60
+ if task == "clean":
61
+ self._task_impl.output_suffix = "clean"
62
+ self._active_cancellation = None
63
+ self._active_progress = None
64
+ self._run_lock = threading.Lock()
65
+ self._last_warnings: list[str] = []
66
+
67
+ def __enter__(self):
68
+ return self
69
+
70
+ def __exit__(self, exc_type, exc_value, traceback):
71
+ self.cleanup()
72
+
73
+ def run(self, request: WipeRequest, on_progress: Optional[ProgressCallback] = None,
74
+ cancellation: Optional[CancellationToken] = None) -> WipeResult:
75
+ if not isinstance(request, WipeRequest):
76
+ raise InvalidInputError("request must be a WipeRequest instance")
77
+ if on_progress is not None and not callable(on_progress):
78
+ raise InvalidInputError("on_progress must be callable")
79
+ if cancellation is not None and not isinstance(cancellation, CancellationToken):
80
+ raise InvalidInputError("cancellation must be a CancellationToken")
81
+ try:
82
+ video = os.fspath(request.video)
83
+ output = os.fspath(request.output_dir)
84
+ mask = os.fspath(request.mask) if request.mask is not None else None
85
+ except TypeError as exc:
86
+ raise InvalidInputError("video, mask, and output_dir must be filesystem paths", cause=exc) from exc
87
+ if not video or not output:
88
+ raise InvalidInputError("video and output_dir must not be empty")
89
+ if not self._run_lock.acquire(blocking=False):
90
+ raise ProcessingError("This WipeEngine is already processing a request", code="ENGINE_BUSY", retryable=True)
91
+ self._active_cancellation = cancellation or CancellationToken()
92
+ self._active_progress = on_progress
93
+ before = self._artifact_snapshot(output)
94
+ try:
95
+ self._emit_progress(ProgressEvent("prepare", 0, 1))
96
+ result_path = self.process(
97
+ video, mask=mask, output=output, detector=request.detector,
98
+ targets=list(request.targets), intent=request.intent, regions=list(request.regions),
99
+ preview=request.preview, confirm=request.confirm, detect_mode=request.detect_mode,
100
+ ocr=request.ocr, detector_mode=request.detector_mode, plan=request.plan,
101
+ progress=lambda done, total: self._emit_progress(ProgressEvent("inpaint", done, total)),
102
+ )
103
+ result = self._build_result(request, result_path, before)
104
+ self._emit_progress(ProgressEvent("complete", 1, 1), check_after=False)
105
+ return result
106
+ except _ProgressCallbackError as exc:
107
+ raise exc.cause
108
+ except (ProcessingCancelledError, WipeError):
109
+ raise
110
+ except ValueError as exc:
111
+ raise InvalidInputError(str(exc), cause=exc) from exc
112
+ except Exception as exc:
113
+ raise ProcessingError(str(exc), code="PROCESSING_FAILED", cause=exc) from exc
114
+ finally:
115
+ self._active_cancellation = None
116
+ self._active_progress = None
117
+ self._run_lock.release()
118
+
119
+ @staticmethod
120
+ def _artifact_snapshot(output_dir: str) -> dict:
121
+ result = {}
122
+ for name in ("auto_mask.png", "clean_candidates.json", "clean_preview.jpg", "benchmark.json", "wipe_plan.json", "wipe_plan_masks.npz"):
123
+ path = os.path.join(output_dir, name)
124
+ try:
125
+ stat = os.stat(path)
126
+ except OSError:
127
+ continue
128
+ result[name] = (stat.st_mtime_ns, stat.st_size)
129
+ return result
130
+
131
+ def _build_result(self, request, output_path, before):
132
+ output_dir = os.fspath(request.output_dir)
133
+ after = self._artifact_snapshot(output_dir)
134
+ benchmark = {}
135
+ try:
136
+ with open(os.path.join(output_dir, "benchmark.json"), encoding="utf-8") as handle:
137
+ benchmark = json.load(handle)
138
+ except (OSError, ValueError):
139
+ pass
140
+ artifacts = [os.path.join(output_dir, name) for name, sig in after.items() if sig != before.get(name)]
141
+ if os.path.isfile(output_path) and output_path not in artifacts:
142
+ artifacts.append(output_path)
143
+ return WipeResult(
144
+ output_path=output_path, backend=benchmark.get("backend", "opencv"),
145
+ mask_source="manual" if request.mask is not None else "auto",
146
+ artifacts=tuple(artifacts), timings=dict(benchmark.get("timing", {})),
147
+ warnings=tuple(self._last_warnings), preview=request.preview,
148
+ )
149
+
150
+ def _check_cancelled(self):
151
+ if self._active_cancellation is not None:
152
+ self._active_cancellation.raise_if_cancelled()
153
+
154
+ def _emit_progress(self, event, *, check_after=True):
155
+ self._check_cancelled()
156
+ if self._active_progress is not None:
157
+ try:
158
+ self._active_progress(event)
159
+ except Exception as exc:
160
+ raise _ProgressCallbackError(exc) from exc
161
+ if check_after:
162
+ self._check_cancelled()
163
+
164
+ def _ensure_model(self):
165
+ if self._task_impl.inpainter is None:
166
+ self._task_impl.inpainter = get_registry().create("opencv", **self._model_options)
167
+ self._task_impl.backend = self._task_impl.inpainter
168
+
169
+ def process(self, video: str, mask: str | None = None, output: str = "result/",
170
+ detector: Optional[TextDetector] = None, targets=None, intent=None,
171
+ agent=None, regions=None, preview=False, confirm=False,
172
+ detect_mode=None, ocr=None, detector_mode=None, progress=None, plan=None) -> str:
173
+ del agent
174
+ if mask is not None and plan is not None:
175
+ raise InvalidInputError("mask and plan are mutually exclusive")
176
+ if plan is not None and self.task != "clean":
177
+ raise InvalidInputError("plan is only supported for the clean task")
178
+ self._last_warnings = []
179
+ self._active_plan = None
180
+ self._task_impl.frame_mask = None
181
+ os.makedirs(output, exist_ok=True)
182
+ started = time.monotonic()
183
+ benchmark = {"video_path": video, "timing": {}, "mask_source": "manual" if mask else "auto"}
184
+ if mask is not None:
185
+ mask_arr = read_mask(mask)
186
+ mask_path = mask
187
+ elif self.task == "clean":
188
+ detected_start = time.monotonic()
189
+ wipe_plan = self._resolve_clean_plan(plan, video, detector, targets, intent, regions, detect_mode, ocr, output, confirm, detector_mode)
190
+ self._last_warnings = list(wipe_plan.warnings)
191
+ if plan is None and not wipe_plan.remove_tracks:
192
+ passthrough = os.path.join(output, f"{os.path.splitext(os.path.basename(video))[0]}_clean.mp4")
193
+ shutil.copy2(video, passthrough)
194
+ print("[videoclean] no overlays found; copied input unchanged")
195
+ return passthrough
196
+ mask_arr = self._union_mask_from_plan(wipe_plan, (wipe_plan.source.height, wipe_plan.source.width))
197
+ mask_path = os.path.join(output, "auto_mask.png")
198
+ if not cv2.imwrite(mask_path, np.clip(mask_arr * 255, 0, 255).astype(np.uint8)):
199
+ raise OSError(f"Failed to write image: {mask_path}")
200
+ benchmark["timing"]["detection_s"] = round(time.monotonic() - detected_start, 3)
201
+ if preview:
202
+ print(f"Preview saved to {output}")
203
+ return output
204
+ else:
205
+ from videoclean.detect import detect_subtitle_mask
206
+ mask_arr = detect_subtitle_mask(video, detector=detector or self._detector)
207
+ mask_path = os.path.join(output, "auto_mask.png")
208
+ cv2.imwrite(mask_path, np.clip(mask_arr * 255, 0, 255).astype(np.uint8))
209
+ if preview:
210
+ print(f"Preview saved to {output}")
211
+ return output
212
+ if self._active_plan is not None:
213
+ validate_plan(self._active_plan, require_remove=True)
214
+ self._ensure_model()
215
+ reader, info = read_frame_info(video)
216
+ try:
217
+ validate_mask_shape(mask_arr, info)
218
+ benchmark.update(width=info["W_ori"], height=info["H_ori"], frame_count=info["len"], fps=round(info["fps"], 2))
219
+ benchmark["mask_area_ratio"] = round(float(np.sum(mask_arr > 0)) / (info["H_ori"] * info["W_ori"]), 6)
220
+ self._task_impl._bm = benchmark
221
+ self._task_impl.mask_path = mask_path
222
+ out_path = self._task_impl.process_video(reader, info, mask_arr, output, video_path=video, progress=progress)
223
+ benchmark["backend"] = "opencv"
224
+ return out_path
225
+ finally:
226
+ reader.release()
227
+ benchmark["timing"]["total_s"] = round(time.monotonic() - started, 3)
228
+ benchmark["output_path"] = locals().get("out_path")
229
+ benchmark["error"] = None
230
+ try:
231
+ with open(os.path.join(output, "benchmark.json"), "w", encoding="utf-8") as handle:
232
+ json.dump(benchmark, handle, indent=2)
233
+ except OSError:
234
+ pass
235
+
236
+ def cleanup(self):
237
+ if not self._run_lock.acquire(blocking=False):
238
+ raise ProcessingError("Cannot clean up a WipeEngine while a request is running", code="ENGINE_BUSY", retryable=True)
239
+ try:
240
+ self._task_impl.cleanup()
241
+ finally:
242
+ self._run_lock.release()
243
+
244
+ @staticmethod
245
+ def _build_recognizer(ocr_mode):
246
+ if ocr_mode == "off":
247
+ return None
248
+ try:
249
+ from videoclean.ocr import recognize_text, _get_engine
250
+ _get_engine()
251
+ return recognize_text
252
+ except Exception:
253
+ if ocr_mode == "rapidocr":
254
+ raise RuntimeError("OCR mode 'rapidocr' requested but rapidocr-onnxruntime is not installed. Install it with: pip install videoclean[ocr]")
255
+ return None
256
+
257
+ def _resolve_clean_plan(self, plan, video, detector, targets, intent, regions, detect_mode, ocr, output, confirm, detector_mode):
258
+ if plan is not None:
259
+ return self._resolve_plan_argument(plan, video)
260
+ result, selected_ids, snapshot, directed = self._detect_clean(video, detector, targets, intent, regions, detect_mode, ocr, output, confirm, detector_mode)
261
+ wipe_plan = self._build_fresh_clean_plan(video, result, selected_ids, snapshot, directed)
262
+ self._write_final_clean_artifacts(result, wipe_plan, output)
263
+ save_wipe_plan(wipe_plan, output)
264
+ return wipe_plan
265
+
266
+ def _build_fresh_clean_plan(self, video, result, selected_ids, snapshot, directed):
267
+ selection = self._explicit_selection_kwargs(result.candidates, selected_ids, directed)
268
+ return build_refined_wipe_plan(
269
+ video, result, compute_source(video), refine=snapshot["detect_mode"] != "fast",
270
+ request=snapshot, progress=lambda done, total: self._emit_progress(ProgressEvent("refine", done, total)),
271
+ check_cancelled=self._check_cancelled, **selection,
272
+ )
273
+
274
+ @staticmethod
275
+ def _write_final_clean_artifacts(result, wipe_plan, output):
276
+ from videoclean.detect import write_clean_artifacts
277
+ remove_ids = {track.id for track in wipe_plan.remove_tracks}
278
+ write_clean_artifacts(result, [candidate for candidate in result.candidates if candidate.id in remove_ids], output)
279
+
280
+ @staticmethod
281
+ def _explicit_selection_kwargs(candidates, selected_ids, user_directed):
282
+ if not user_directed:
283
+ return {"explicit_remove_ids": set(), "explicit_keep_ids": set()}
284
+ selected = set(selected_ids)
285
+ return {"explicit_remove_ids": selected, "explicit_keep_ids": {candidate.id for candidate in candidates} - selected}
286
+
287
+ def _detect_clean(self, video, detector, targets, intent, regions, detect_mode, ocr, output, confirm, detector_mode):
288
+ from videoclean.detect import detect_clean_candidates, infer_regions_from_text, infer_targets_from_text, normalize_target, resolve_detect_params, select_clean_candidates, write_clean_artifacts
289
+ targets = list(targets or [])
290
+ requested_regions = list(regions or [])
291
+ intent_text = " ".join([*targets, intent or ""])
292
+ requested_regions.extend(infer_regions_from_text(intent_text))
293
+ requested_regions = list(dict.fromkeys(requested_regions))
294
+ effective_targets = list(targets) + infer_targets_from_text(" ".join(targets))
295
+ if requested_regions:
296
+ effective_targets.append("region")
297
+ effective_targets = list(dict.fromkeys(effective_targets))
298
+ normalized = {normalize_target(target) for target in effective_targets}
299
+ detect_text = not requested_regions and not normalized or bool(normalized & {"subtitle", "timestamp", "watermark", "scene_text", "unknown_text"}) or bool(intent and not normalized)
300
+ params = resolve_detect_params(detect_mode or self._detect_mode, has_subtitle_target="subtitle" in normalized)
301
+ recognizer = self._build_recognizer(ocr or self._ocr)
302
+ mode = detector_mode or "dbnet"
303
+ if mode not in {"dbnet", "hybrid"}:
304
+ raise ValueError("detector_mode must be 'dbnet' or 'hybrid'")
305
+ if detector is None:
306
+ from videoclean.detect import HybridTextDetector, _default_detector
307
+ detector = _default_detector()
308
+ if mode == "hybrid":
309
+ detector = HybridTextDetector(detector)
310
+ self._emit_progress(ProgressEvent("detect", 0, params["sample_count"], message=f"Scanning {params['sample_count']} sampled frames"))
311
+ result = detect_clean_candidates(video, detector=detector, regions=requested_regions, detect_text=detect_text, include_logo="logo" in normalized, include_translucent_watermark="watermark" in normalized, sample_count=params["sample_count"], consistency=params["consistency"], subtitle_fallback=params["subtitle_fallback"], recognizer=recognizer)
312
+ selected = select_clean_candidates(result.candidates, targets=effective_targets, intent=intent)
313
+ print(f"[videoclean] found {len(result.candidates)} candidate(s); selected {len(selected)}")
314
+ if not result.candidates:
315
+ print("[videoclean] no text or overlay candidates were detected")
316
+ write_clean_artifacts(result, selected, output)
317
+ if confirm:
318
+ selected = self._confirm_candidates(result.candidates, selected)
319
+ write_clean_artifacts(result, selected, output)
320
+ self._emit_progress(ProgressEvent("detect", 1, 1))
321
+ return result, {candidate.id for candidate in selected}, {"intent": intent, "targets": effective_targets, "regions": requested_regions, "detect_mode": detect_mode or self._detect_mode, "ocr": ocr or self._ocr, "detector_mode": mode}, bool(targets or intent or regions or confirm)
322
+
323
+ @staticmethod
324
+ def _confirm_candidates(candidates, selected):
325
+ selected_ids = {candidate.id for candidate in selected}
326
+ for candidate in candidates:
327
+ marker = "*" if candidate.id in selected_ids else " "
328
+ print(f"{marker} {candidate.id}: {candidate.label} ({candidate.reason}, confidence {candidate.confidence:.2f})")
329
+ answer = input("Remove candidate ids separated by commas, press Enter to accept, or type 'none': ").strip()
330
+ if not answer:
331
+ return list(selected)
332
+ if answer.lower() in {"none", "cancel", "no"}:
333
+ return []
334
+ wanted = {item.strip() for item in answer.split(",") if item.strip()}
335
+ return [candidate for candidate in candidates if candidate.id in wanted]
336
+
337
+ @staticmethod
338
+ def _resolve_plan_argument(plan, video):
339
+ if isinstance(plan, WipePlan):
340
+ validate_plan(plan, require_remove=True)
341
+ actual = compute_source(video)
342
+ if actual.sha256 != plan.source.sha256 or (actual.width, actual.height, actual.frame_count) != (plan.source.width, plan.source.height, plan.source.frame_count):
343
+ raise InvalidInputError("plan source does not match the video")
344
+ return plan
345
+ return load_wipe_plan(os.fspath(plan), video_path=video)
346
+
347
+ def _union_mask_from_plan(self, plan, frame_shape):
348
+ from types import SimpleNamespace
349
+ from videoclean.detect import mask_from_candidates
350
+ adapters = []
351
+ for track in plan.remove_tracks:
352
+ if track.mask is None:
353
+ raise InvalidInputError(f"remove track {track.id} has no precise mask; cannot build union")
354
+ arr = np.asarray(track.mask)
355
+ adapters.append(SimpleNamespace(mask=arr[:, :, None] if arr.ndim == 2 else arr, bbox=track.bbox))
356
+ return mask_from_candidates(adapters, frame_shape, feather_radius=self._task_impl.feather_radius)
357
+
358
+
359
+ def remove_text(video: str, mask: str | None = None, output: str = "result/", gap: int = 10, dual: bool = False, detector=None) -> str:
360
+ """Remove hardcoded subtitles using OpenCV inpainting."""
361
+ with WipeEngine(task="detext", gap=gap, dual=dual, detector=detector) as engine:
362
+ return engine.process(video=video, mask=mask, output=output)
src/videoclean/errors.py ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Stable public exceptions for the VideoWipe SDK."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Optional
5
+
6
+
7
+ class WipeError(RuntimeError):
8
+ """Base class for errors exposed by :meth:`WipeEngine.run`.
9
+
10
+ ``cause`` preserves implementation diagnostics without making backend-
11
+ specific exception types part of the public contract. Treat it as
12
+ sensitive: external backends may include local paths or stderr in it.
13
+ """
14
+
15
+ code = "WIPE_ERROR"
16
+
17
+ def __init__(
18
+ self,
19
+ message: str,
20
+ *,
21
+ code: Optional[str] = None,
22
+ retryable: bool = False,
23
+ cause: Optional[BaseException] = None,
24
+ ) -> None:
25
+ super().__init__(message)
26
+ self.code = code or type(self).code
27
+ self.retryable = retryable
28
+ self.cause = cause
29
+
30
+
31
+ class InvalidInputError(WipeError):
32
+ """The request cannot be processed as supplied."""
33
+
34
+ code = "INVALID_INPUT"
35
+
36
+
37
+ class BackendUnavailableError(WipeError):
38
+ """No usable inference backend or model is available."""
39
+
40
+ code = "BACKEND_UNAVAILABLE"
41
+
42
+
43
+ class ProcessingCancelledError(WipeError):
44
+ """The caller cancelled a running request at a safe boundary."""
45
+
46
+ code = "PROCESSING_CANCELLED"
47
+
48
+
49
+ class ProcessingError(WipeError):
50
+ """Video processing failed after the request was accepted."""
51
+
52
+ code = "PROCESSING_FAILED"
src/videoclean/inpainters/__init__.py ADDED
@@ -0,0 +1,8 @@
 
 
 
 
 
 
 
 
 
1
+ """OpenCV inpainting backend and registry."""
2
+ from videoclean.inpainters.base import InpaintJob, InpaintOutcome, Inpainter
3
+ from videoclean.inpainters.opencv import OpenCVInpainter
4
+ from videoclean.inpainters.registry import InpainterRegistry, get_registry, register_inpainter
5
+
6
+ register_inpainter("opencv", OpenCVInpainter)
7
+
8
+ __all__ = ["Inpainter", "InpaintJob", "InpaintOutcome", "OpenCVInpainter", "InpainterRegistry", "get_registry", "register_inpainter"]
src/videoclean/inpainters/__pycache__/__init__.cpython-314.pyc ADDED
Binary file (595 Bytes). View file
 
src/videoclean/inpainters/__pycache__/base.cpython-314.pyc ADDED
Binary file (5.5 kB). View file
 
src/videoclean/inpainters/__pycache__/opencv.cpython-314.pyc ADDED
Binary file (9.76 kB). View file
 
src/videoclean/inpainters/__pycache__/registry.cpython-314.pyc ADDED
Binary file (3.23 kB). View file
 
src/videoclean/inpainters/base.py ADDED
@@ -0,0 +1,100 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Inpainter protocol: the pluggable unit for video inpainting models.
2
+
3
+ An Inpainter takes an :class:`InpaintJob` (whole-video contract) and returns an
4
+ :class:`InpaintOutcome`. Two implementation shapes are supported equally:
5
+
6
+ * **Frame-based** (e.g. STTN): reads frames from ``job.reader``, runs an
7
+ internal segment loop, and streams output via ffmpeg.
8
+ * **File-based** (e.g. an external subprocess): runs over the whole video file
9
+ and returns the output path; it ignores ``job.reader``.
10
+
11
+ The protocol deliberately lives at the whole-video layer rather than
12
+ frames-in/frames-out, because some models (ProPainter) cannot consume an
13
+ in-memory frame stream.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ from dataclasses import dataclass, field
18
+ from typing import Callable, Optional, Protocol
19
+
20
+ import numpy as np
21
+
22
+
23
+ @dataclass
24
+ class InpaintJob:
25
+ """Whole-video inpainting request.
26
+
27
+ Attributes:
28
+ video_path: input video file path.
29
+ mask: binary mask, shape ``(H, W, 1)``, values in ``{0, 1}``.
30
+ output_dir: directory for the output video and artifacts.
31
+ fps, frame_count, width, height: video metadata.
32
+ device: ``"auto"`` | ``"cpu"`` | ``"cuda"``.
33
+ dual: when True, emit side-by-side original + inpainted output.
34
+ gap: segment-length hint used by frame-based inpainters.
35
+ output_suffix: filename suffix for the output video (e.g. ``"detext"``).
36
+ reader: ``cv2.VideoCapture`` for frame-based inpainters; may be ``None``
37
+ for file-based inpainters. The caller owns the reader lifecycle.
38
+ progress: optional ``(frames_done, frames_total)`` callback.
39
+ metrics: mutable dict (typically the benchmark ``timing`` dict) the
40
+ inpainter writes phase timings into.
41
+ mask_path: mask file path for file-based inpainters (e.g. the external
42
+ subprocess); the ``mask`` ndarray is ignored by those inpainters.
43
+ feather_radius: Gaussian alpha radius applied to bbox-only mask
44
+ candidates so the inpainting blend produces a soft seam. ``0``
45
+ keeps the legacy hard binary mask (used by the eval IoU path).
46
+ frame_mask: optional ``callable(global_frame_index) -> (H, W) mask``.
47
+ When set, the frame-based inpainter blends each frame with this
48
+ per-frame mask instead of the static ``mask`` ndarray, so a
49
+ temporal WipePlan can close subtitle gaps and spare inactive
50
+ regions. ``None`` keeps the legacy whole-video static mask.
51
+ """
52
+
53
+ video_path: str
54
+ mask: np.ndarray
55
+ output_dir: str
56
+ fps: float
57
+ frame_count: int
58
+ width: int
59
+ height: int
60
+ device: str = "auto"
61
+ dual: bool = False
62
+ gap: int = 200
63
+ output_suffix: str = "detext"
64
+ reader: object = None
65
+ progress: Optional[Callable[[int, int], None]] = None
66
+ metrics: dict = field(default_factory=dict)
67
+ mask_path: Optional[str] = None
68
+ feather_radius: int = 0
69
+ frame_mask: Optional[Callable[[int], np.ndarray]] = None
70
+
71
+
72
+ @dataclass
73
+ class InpaintOutcome:
74
+ """Result of an :meth:`Inpainter.inpaint` call."""
75
+
76
+ output_path: str
77
+ backend: str # label written to benchmark.json
78
+
79
+
80
+ class Inpainter(Protocol):
81
+ """Pluggable inpainting model.
82
+
83
+ Lifecycle: :meth:`load` (engine-driven, once) -> :meth:`inpaint` per video
84
+ -> :meth:`cleanup`. STTN keeps a loaded backend across videos; file-based
85
+ inpainters may be effectively stateless.
86
+ """
87
+
88
+ name: str
89
+
90
+ def load(self, weight_path: Optional[str], device: str = "auto") -> None:
91
+ """Load once; custom adapters receive None when no weight was set."""
92
+ ...
93
+
94
+ def inpaint(self, job: InpaintJob) -> InpaintOutcome:
95
+ """Inpaint one video; return the output path and a backend label."""
96
+ ...
97
+
98
+ def cleanup(self) -> None:
99
+ """Release model and GPU memory."""
100
+ ...
src/videoclean/inpainters/opencv.py ADDED
@@ -0,0 +1,134 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Fixed-overlay OpenCV inpainter.
2
+
3
+ Uses one spatial mask on every frame, which is appropriate for persistent
4
+ watermarks and logos that temporal video inpainters can reproduce.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import subprocess
10
+ import tempfile
11
+ import time
12
+
13
+ import cv2
14
+ import numpy as np
15
+
16
+ from videoclean.inpainters.base import InpaintJob, InpaintOutcome
17
+
18
+
19
+ class OpenCVInpainter:
20
+ """Inpaint every frame with ``cv2.inpaint`` and a stable mask."""
21
+
22
+ name = "opencv"
23
+
24
+ def __init__(self, method: str = "telea", radius: float = 3.0, dilate: int = 0):
25
+ if method not in {"telea", "ns"}:
26
+ raise ValueError("method must be 'telea' or 'ns'")
27
+ if radius <= 0:
28
+ raise ValueError("radius must be greater than zero")
29
+ if dilate < 0:
30
+ raise ValueError("dilate must be non-negative")
31
+ self.method = method
32
+ self.radius = float(radius)
33
+ self.dilate = int(dilate)
34
+ self._method_flag = cv2.INPAINT_TELEA if method == "telea" else cv2.INPAINT_NS
35
+
36
+ def load(self, weight_path=None, device: str = "auto") -> None:
37
+ """OpenCV inpainting has no model weights to load."""
38
+
39
+ def cleanup(self) -> None:
40
+ """OpenCV inpainting has no persistent resources."""
41
+
42
+ def _prepare_mask(self, job: InpaintJob) -> np.ndarray:
43
+ mask = np.asarray(job.mask)
44
+ if mask.ndim == 3:
45
+ mask = mask[:, :, 0]
46
+ if mask.ndim != 2 or mask.shape != (job.height, job.width):
47
+ raise ValueError(
48
+ f"OpenCV mask must have shape {(job.height, job.width)}, got {mask.shape}"
49
+ )
50
+ if np.issubdtype(mask.dtype, np.floating):
51
+ max_value = float(np.max(mask)) if mask.size else 0.0
52
+ if max_value <= 1.0:
53
+ mask = np.clip(mask * 255.0, 0, 255).astype(np.uint8)
54
+ else:
55
+ mask = np.clip(mask, 0, 255).astype(np.uint8)
56
+ else:
57
+ mask = np.where(mask > 0, 255, 0).astype(np.uint8)
58
+ if self.dilate:
59
+ size = self.dilate * 2 + 1
60
+ kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (size, size))
61
+ mask = cv2.dilate(mask, kernel, iterations=1)
62
+ if not np.any(mask):
63
+ raise ValueError("Mask has no inpaintable regions")
64
+ return mask
65
+
66
+ def inpaint(self, job: InpaintJob) -> InpaintOutcome:
67
+ if job.reader is None:
68
+ raise ValueError("OpenCVInpainter requires job.reader (a cv2.VideoCapture)")
69
+ mask = self._prepare_mask(job)
70
+ stem = os.path.splitext(os.path.basename(job.video_path))[0] if job.video_path else "output"
71
+ output_path = os.path.join(job.output_dir, f"{stem}_{job.output_suffix}.mp4")
72
+ os.makedirs(job.output_dir, exist_ok=True)
73
+ out_h = job.height * 2 if job.dual else job.height
74
+ ffmpeg_cmd = [
75
+ "ffmpeg", "-y", "-loglevel", "error", "-nostats",
76
+ "-f", "rawvideo", "-vcodec", "rawvideo",
77
+ "-s", f"{job.width}x{out_h}", "-pix_fmt", "bgr24",
78
+ "-r", str(job.fps), "-i", "-",
79
+ ]
80
+ if job.video_path:
81
+ ffmpeg_cmd += ["-i", job.video_path]
82
+ ffmpeg_cmd += ["-map", "0:v"]
83
+ if job.video_path:
84
+ ffmpeg_cmd += ["-map", "1:a?"]
85
+ ffmpeg_cmd += [
86
+ "-c:v", "libx264", "-crf", "18", "-preset", "medium",
87
+ "-pix_fmt", "yuv420p",
88
+ ]
89
+ if job.video_path:
90
+ ffmpeg_cmd += ["-c:a", "aac"]
91
+ ffmpeg_cmd += ["-movflags", "+faststart", output_path]
92
+
93
+ stderr_file = tempfile.TemporaryFile()
94
+ pipe = subprocess.Popen(ffmpeg_cmd, stdin=subprocess.PIPE, stderr=stderr_file)
95
+ stdin_closed = False
96
+ failed = False
97
+ started = time.monotonic()
98
+ done = 0
99
+ try:
100
+ while True:
101
+ ok, frame = job.reader.read()
102
+ if not ok:
103
+ break
104
+ cleaned = cv2.inpaint(frame, mask, self.radius, self._method_flag)
105
+ if job.dual:
106
+ cleaned = np.vstack([frame, cleaned])
107
+ pipe.stdin.write(cleaned.tobytes())
108
+ done += 1
109
+ if job.progress is not None:
110
+ job.progress(done, job.frame_count)
111
+ pipe.stdin.close()
112
+ stdin_closed = True
113
+ pipe.wait()
114
+ if isinstance(job.metrics, dict):
115
+ job.metrics["inpainting_s"] = round(time.monotonic() - started, 3)
116
+ except Exception:
117
+ failed = True
118
+ raise
119
+ finally:
120
+ if not stdin_closed and pipe.stdin is not None:
121
+ pipe.stdin.close()
122
+ if pipe.poll() is None:
123
+ pipe.terminate()
124
+ pipe.wait()
125
+ if failed:
126
+ stderr_file.close()
127
+ if pipe.returncode != 0:
128
+ stderr_file.seek(0)
129
+ error = stderr_file.read().decode(errors="replace")
130
+ stderr_file.close()
131
+ raise RuntimeError(f"FFmpeg exited with code {pipe.returncode}:\n{error}")
132
+ stderr_file.close()
133
+ print(f"Saved to {output_path}")
134
+ return InpaintOutcome(output_path=output_path, backend=self.name)
src/videoclean/inpainters/registry.py ADDED
@@ -0,0 +1,44 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Name-based registry for Inpainter implementations."""
2
+ from __future__ import annotations
3
+
4
+ from typing import Callable
5
+
6
+ from videoclean.inpainters.base import Inpainter
7
+
8
+
9
+ class InpainterRegistry:
10
+ """Maps inpainter names to factory callables.
11
+
12
+ Factories are called with keyword options by :meth:`create`; the built-in
13
+ STTN factory accepts no options.
14
+ """
15
+
16
+ def __init__(self) -> None:
17
+ self._factories: dict[str, Callable[..., Inpainter]] = {}
18
+
19
+ def register(self, name: str, factory: Callable[..., Inpainter]) -> None:
20
+ if name in self._factories:
21
+ raise ValueError(f"Inpainter already registered: {name}")
22
+ self._factories[name] = factory
23
+
24
+ def create(self, name: str, **options) -> Inpainter:
25
+ if name not in self._factories:
26
+ raise ValueError(
27
+ f"Unknown inpainter: {name}. Available: {sorted(self._factories)}"
28
+ )
29
+ return self._factories[name](**options)
30
+
31
+ def names(self) -> list[str]:
32
+ return sorted(self._factories)
33
+
34
+
35
+ _registry = InpainterRegistry()
36
+
37
+
38
+ def register_inpainter(name: str, factory: Callable[..., Inpainter]) -> None:
39
+ """Register an inpainter factory under *name*."""
40
+ _registry.register(name, factory)
41
+
42
+
43
+ def get_registry() -> InpainterRegistry:
44
+ return _registry
src/videoclean/ocr.py ADDED
@@ -0,0 +1,77 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Optional OCR text recognition for detected text crops.
2
+
3
+ Requires ``rapidocr-onnxruntime`` (install with ``pip install videoclean[ocr]``).
4
+ Importing this module fails gracefully when the dependency is not installed.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Optional
10
+
11
+ import numpy as np
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class OCRRegion:
16
+ """One RapidOCR detection with polygon, text, and confidence."""
17
+
18
+ points: np.ndarray
19
+ text: str
20
+ confidence: float
21
+
22
+ _engine = None
23
+
24
+
25
+ def _get_engine():
26
+ """Lazily initialize the RapidOCR engine."""
27
+ global _engine
28
+ if _engine is not None:
29
+ return _engine
30
+ try:
31
+ from rapidocr_onnxruntime import RapidOCR
32
+ except ImportError as exc:
33
+ raise ImportError(
34
+ "rapidocr-onnxruntime is not installed. "
35
+ "Install it with: pip install videoclean[ocr]"
36
+ ) from exc
37
+ _engine = RapidOCR()
38
+ return _engine
39
+
40
+
41
+ def detect_regions(image: np.ndarray) -> list[OCRRegion]:
42
+ """Detect and recognize text regions in a BGR image."""
43
+ result, _ = _get_engine()(image)
44
+ regions: list[OCRRegion] = []
45
+ for item in result or []:
46
+ if not isinstance(item, (list, tuple)) or len(item) < 3:
47
+ continue
48
+ try:
49
+ points = np.asarray(item[0], dtype=np.float32).reshape(-1, 2)
50
+ confidence = float(item[2])
51
+ except (TypeError, ValueError):
52
+ continue
53
+ if points.shape[0] < 3 or not np.isfinite(points).all():
54
+ continue
55
+ if confidence <= 0:
56
+ continue
57
+ regions.append(OCRRegion(points, str(item[1] or ""), confidence))
58
+ return regions
59
+
60
+
61
+ def recognize_text(image_crop: np.ndarray) -> Optional[str]:
62
+ """Recognize text in a single image crop.
63
+
64
+ Args:
65
+ image_crop: BGR image as a numpy array (H, W, 3).
66
+
67
+ Returns:
68
+ Recognized text string, or ``None`` if no text is found.
69
+ """
70
+ regions = detect_regions(image_crop)
71
+ texts = [region.text for region in regions if region.text]
72
+ return " ".join(texts) if texts else None
73
+
74
+
75
+ def recognize_regions(image: np.ndarray) -> list[OCRRegion]:
76
+ """Alias for :func:`detect_regions` for detector integrations."""
77
+ return detect_regions(image)
src/videoclean/plan.py ADDED
@@ -0,0 +1,791 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """WipePlan v1: serializable, reviewable, deterministically-executable plan.
2
+
3
+ A :class:`WipePlan` is the intermediate representation between detection and
4
+ inpainting. Each detected candidate becomes an addressable *track* with:
5
+
6
+ - an explicit ``remove`` | ``keep`` action,
7
+ - a stable spatial mask (stored in a sidecar NPZ, not the JSON),
8
+ - half-open temporal ``[start, end)`` segments saying when it is active.
9
+
10
+ Schema v1 is a *screen-overlay* model: one stable spatial mask per track plus
11
+ time intervals. It is not a general motion-object tracker — there is no
12
+ per-frame mask propagation. That is the minimum model the current failure
13
+ facts require: it closes subtitle-gap false erasures and lets persistent top
14
+ overlays (logos, credits) be flagged ``keep`` instead of misclassified as
15
+ subtitles.
16
+
17
+ The JSON stays agent-readable; precise binary masks live in a sidecar
18
+ ``wipe_plan_masks.npz``. The NPZ holds only raw ``uint8`` arrays and is loaded
19
+ with ``allow_pickle=False``; nothing picklable is ever written.
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import json
25
+ import os
26
+ from collections.abc import Mapping, Sequence
27
+ from dataclasses import dataclass, field
28
+ from typing import Any
29
+
30
+ import cv2
31
+ import numpy as np
32
+
33
+ from videoclean.errors import InvalidInputError
34
+
35
+ SCHEMA_VERSION = 1
36
+ PLAN_KIND = "wipe_plan"
37
+ JSON_FILENAME = "wipe_plan.json"
38
+ MASK_FILENAME = "wipe_plan_masks.npz"
39
+
40
+ _ACTION_VALUES = ("remove", "keep")
41
+ _TOP_REGION_FRACTION = 0.30 # mirrors detect._classify_region's top-subtitle threshold
42
+ _PERSISTENT_PRESENCE = 0.80 # plan Rule 6: persistent-overlay safety default
43
+ _COARSE_GAP_SECONDS = 2.0 # plan Rule 8: temporal-coarseness warning threshold
44
+
45
+
46
+ # ── helpers ──────────────────────────────────────────────────────────────────
47
+
48
+ def _sha256_file(path: str, chunk: int = 1 << 20) -> str:
49
+ h = hashlib.sha256()
50
+ with open(path, "rb") as fh:
51
+ for block in iter(lambda: fh.read(chunk), b""):
52
+ h.update(block)
53
+ return h.hexdigest()
54
+
55
+
56
+ def _assert_bare_name(child: str) -> None:
57
+ """Reject anything that is not a bare basename (no separator/absolute/``..``)."""
58
+ if not child or child in (".", "..") or os.path.isabs(child) or child != os.path.basename(child):
59
+ raise InvalidInputError(f"unsafe plan-relative path: {child!r}")
60
+
61
+
62
+ def _child_path(parent: str, child: str) -> str:
63
+ """Join ``parent``/``child`` and refuse any path that escapes *parent*.
64
+
65
+ First rejects non-basename names (absolute, separators, ``.``/``..``).
66
+ Then resolves both *parent* and the joined *child* to their real paths and
67
+ verifies the resolved child still lives inside the resolved parent via
68
+ :func:`os.path.commonpath`. This catches an existing sidecar symlink that
69
+ points outside the plan directory before any read/write/hash/``np.load``.
70
+ """
71
+ _assert_bare_name(child)
72
+ joined = os.path.join(parent, child)
73
+ resolved_parent = os.path.realpath(parent)
74
+ resolved_child = os.path.realpath(joined)
75
+ try:
76
+ common = os.path.commonpath([resolved_parent, resolved_child])
77
+ except ValueError:
78
+ common = ""
79
+ if common != resolved_parent:
80
+ raise InvalidInputError(
81
+ f"unsafe plan-relative path escapes plan directory: {child!r}"
82
+ )
83
+ return joined
84
+
85
+
86
+ # ── data types ───────────────────────────────────────────────────────────────
87
+
88
+ @dataclass
89
+ class Source:
90
+ """Identity of the source video the plan is bound to."""
91
+ basename: str
92
+ sha256: str
93
+ width: int
94
+ height: int
95
+ fps: float
96
+ frame_count: int
97
+
98
+ def to_dict(self) -> dict:
99
+ return {
100
+ "basename": self.basename,
101
+ "sha256": self.sha256,
102
+ "width": int(self.width),
103
+ "height": int(self.height),
104
+ "fps": float(self.fps),
105
+ "frame_count": int(self.frame_count),
106
+ }
107
+
108
+ @classmethod
109
+ def from_dict(cls, d: Mapping[str, Any]) -> Source:
110
+ return cls(
111
+ basename=str(d["basename"]),
112
+ sha256=str(d["sha256"]),
113
+ width=int(d["width"]),
114
+ height=int(d["height"]),
115
+ fps=float(d["fps"]),
116
+ frame_count=int(d["frame_count"]),
117
+ )
118
+
119
+
120
+ @dataclass
121
+ class Segment:
122
+ """Half-open frame interval ``[start, end)``."""
123
+
124
+ start: int
125
+ end: int
126
+
127
+ def __post_init__(self) -> None:
128
+ self.start = int(self.start)
129
+ self.end = int(self.end)
130
+
131
+ def contains(self, frame: int) -> bool:
132
+ return self.start <= frame < self.end
133
+
134
+ def to_dict(self) -> list[int]:
135
+ return [self.start, self.end]
136
+
137
+ @classmethod
138
+ def from_value(cls, value) -> Segment:
139
+ return cls(start=int(value[0]), end=int(value[1]))
140
+
141
+
142
+ @dataclass
143
+ class Track:
144
+ """One addressable candidate in a plan."""
145
+
146
+ id: str
147
+ type: str
148
+ label: str
149
+ action: str
150
+ bbox: tuple[int, int, int, int]
151
+ confidence: float
152
+ presence_fraction: float
153
+ decision_reason: str
154
+ segments: list[Segment]
155
+ mask_key: str
156
+ # In-memory only; never serialized to JSON. Loaded from the sidecar NPZ.
157
+ mask: np.ndarray | None = field(default=None, repr=False)
158
+
159
+ def to_dict(self) -> dict:
160
+ return {
161
+ "id": self.id,
162
+ "type": self.type,
163
+ "label": self.label,
164
+ "action": self.action,
165
+ "bbox": list(self.bbox),
166
+ "confidence": round(float(self.confidence), 4),
167
+ "presence_fraction": round(float(self.presence_fraction), 4),
168
+ "decision_reason": self.decision_reason,
169
+ "segments": [s.to_dict() for s in self.segments],
170
+ "mask_key": self.mask_key,
171
+ }
172
+
173
+ @classmethod
174
+ def from_dict(cls, d: Mapping[str, Any]) -> Track:
175
+ return cls(
176
+ id=str(d["id"]),
177
+ type=str(d["type"]),
178
+ label=str(d["label"]),
179
+ action=str(d["action"]),
180
+ bbox=tuple(int(v) for v in d["bbox"]),
181
+ confidence=float(d["confidence"]),
182
+ presence_fraction=float(d["presence_fraction"]),
183
+ decision_reason=str(d["decision_reason"]),
184
+ segments=[Segment.from_value(s) for s in d["segments"]],
185
+ mask_key=str(d["mask_key"]),
186
+ )
187
+
188
+ @property
189
+ def full_video(self) -> bool:
190
+ """True if this track is active on every frame."""
191
+ return len(self.segments) == 1 and self.segments[0].start == 0
192
+
193
+
194
+ @dataclass
195
+ class MaskAsset:
196
+ filename: str
197
+ sha256: str
198
+
199
+ def to_dict(self) -> dict:
200
+ return {"filename": self.filename, "sha256": self.sha256}
201
+
202
+ @classmethod
203
+ def from_dict(cls, d: Mapping[str, Any]) -> MaskAsset:
204
+ return cls(filename=str(d["filename"]), sha256=str(d["sha256"]))
205
+
206
+
207
+ @dataclass
208
+ class TemporalResolution:
209
+ """Honest statement of the plan's temporal precision."""
210
+ max_gap_frames: int
211
+ max_gap_seconds: float
212
+ max_boundary_error_frames: int
213
+
214
+ def to_dict(self) -> dict:
215
+ return {
216
+ "max_gap_frames": int(self.max_gap_frames),
217
+ "max_gap_seconds": round(float(self.max_gap_seconds), 4),
218
+ "max_boundary_error_frames": int(self.max_boundary_error_frames),
219
+ }
220
+
221
+ @classmethod
222
+ def from_dict(cls, d: Mapping[str, Any]) -> TemporalResolution:
223
+ return cls(
224
+ max_gap_frames=int(d["max_gap_frames"]),
225
+ max_gap_seconds=float(d["max_gap_seconds"]),
226
+ max_boundary_error_frames=int(d["max_boundary_error_frames"]),
227
+ )
228
+
229
+
230
+ @dataclass
231
+ class WipePlan:
232
+ kind: str
233
+ schema_version: int
234
+ source: Source
235
+ request: dict
236
+ temporal_resolution: TemporalResolution
237
+ mask_asset: MaskAsset
238
+ tracks: list[Track]
239
+ warnings: list[str] = field(default_factory=list)
240
+
241
+ def to_dict(self) -> dict:
242
+ return {
243
+ "kind": self.kind,
244
+ "schema_version": self.schema_version,
245
+ "source": self.source.to_dict(),
246
+ "request": dict(self.request),
247
+ "temporal_resolution": self.temporal_resolution.to_dict(),
248
+ "mask_asset": self.mask_asset.to_dict(),
249
+ "tracks": [t.to_dict() for t in self.tracks],
250
+ "warnings": list(self.warnings),
251
+ }
252
+
253
+ @classmethod
254
+ def from_dict(cls, d: Mapping[str, Any]) -> WipePlan:
255
+ return cls(
256
+ kind=str(d["kind"]),
257
+ schema_version=int(d["schema_version"]),
258
+ source=Source.from_dict(d["source"]),
259
+ request=dict(d.get("request", {})),
260
+ temporal_resolution=TemporalResolution.from_dict(d["temporal_resolution"]),
261
+ mask_asset=MaskAsset.from_dict(d["mask_asset"]),
262
+ tracks=[Track.from_dict(t) for t in d["tracks"]],
263
+ warnings=list(d.get("warnings", [])),
264
+ )
265
+
266
+ @property
267
+ def remove_tracks(self) -> list[Track]:
268
+ return [t for t in self.tracks if t.action == "remove"]
269
+
270
+ @property
271
+ def keep_tracks(self) -> list[Track]:
272
+ return [t for t in self.tracks if t.action == "keep"]
273
+
274
+
275
+ # ── source / temporal helpers ────────────────────────────────────────────────
276
+
277
+ def compute_source(video_path: str) -> Source:
278
+ """Read video identity (dimensions, fps, frame_count) and SHA-256."""
279
+ if not os.path.isfile(video_path):
280
+ raise InvalidInputError(f"Video not found: {video_path}")
281
+ cap = cv2.VideoCapture(video_path)
282
+ if not cap.isOpened():
283
+ raise InvalidInputError(f"Cannot open video: {video_path}")
284
+ try:
285
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
286
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
287
+ fps = float(cap.get(cv2.CAP_PROP_FPS) or 0.0)
288
+ # Round to match tasks.base.read_frame_info (int(x + 0.5)); truncating
289
+ # here would make the plan's frame_count one short of STTN's loop bound
290
+ # for non-integer CAP_PROP_FRAME_COUNT, leaving the trailing frame
291
+ # un-inpainted.
292
+ frame_count = int((cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0) + 0.5)
293
+ finally:
294
+ cap.release()
295
+ return Source(
296
+ basename=os.path.basename(video_path),
297
+ sha256=_sha256_file(video_path),
298
+ width=width,
299
+ height=height,
300
+ fps=fps,
301
+ frame_count=frame_count,
302
+ )
303
+
304
+
305
+ def segments_from_presence(
306
+ sample_indices: Sequence[int],
307
+ presence_set: set[int],
308
+ frame_count: int,
309
+ ) -> list[Segment]:
310
+ """Compress per-sample presence into half-open segments.
311
+
312
+ Each frame takes the presence state of its **nearest sampled frame**; the
313
+ switch point is the midpoint between adjacent samples (ties resolve to the
314
+ earlier sample), so the worst-case boundary error is half the max sample
315
+ gap. Returns sorted, non-overlapping ``[start, end)`` segments.
316
+ """
317
+ samples = sorted(int(s) for s in sample_indices if 0 <= int(s) < frame_count)
318
+ if not samples or frame_count <= 0:
319
+ return []
320
+ present_at_sample = np.fromiter(
321
+ (1 if s in presence_set else 0 for s in samples), dtype=np.int8
322
+ )
323
+ samples_arr = np.asarray(samples, dtype=np.int64)
324
+ frames = np.arange(frame_count, dtype=np.int64)
325
+ pos = np.searchsorted(samples_arr, frames)
326
+ lo = np.clip(pos - 1, 0, len(samples) - 1)
327
+ hi = np.clip(pos, 0, len(samples) - 1)
328
+ dist_lo = frames - samples_arr[lo]
329
+ dist_hi = samples_arr[hi] - frames
330
+ # ties (dist_hi == dist_lo) keep the earlier sample -> midpoint switch
331
+ choose_hi = (pos < len(samples)) & (dist_hi < dist_lo)
332
+ nearest = np.where(choose_hi, hi, lo)
333
+ present = present_at_sample[nearest].astype(bool)
334
+
335
+ segments: list[Segment] = []
336
+ start: int | None = None
337
+ for f in range(frame_count):
338
+ if present[f] and start is None:
339
+ start = f
340
+ elif not present[f] and start is not None:
341
+ segments.append(Segment(start, f))
342
+ start = None
343
+ if start is not None:
344
+ segments.append(Segment(start, frame_count))
345
+ return segments
346
+
347
+
348
+ def _temporal_resolution(
349
+ sample_indices: Sequence[int], frame_count: int, fps: float
350
+ ) -> TemporalResolution:
351
+ s = sorted(int(x) for x in sample_indices)
352
+ if len(s) < 2 or frame_count <= 0:
353
+ return TemporalResolution(0, 0.0, 0)
354
+ gaps = [s[i] - s[i - 1] for i in range(1, len(s))]
355
+ max_gap = max(gaps)
356
+ seconds = (max_gap / fps) if fps > 0 else 0.0
357
+ return TemporalResolution(
358
+ max_gap_frames=int(max_gap),
359
+ max_gap_seconds=seconds,
360
+ max_boundary_error_frames=int(max_gap // 2),
361
+ )
362
+
363
+
364
+ # ── action resolution + plan construction ────────────────────────────────────
365
+
366
+ def _resolve_action(
367
+ candidate,
368
+ presence_fraction: float,
369
+ height: int,
370
+ explicit_remove_ids: set[str],
371
+ explicit_keep_ids: set[str],
372
+ loaded_actions: Mapping[str, str],
373
+ ) -> tuple[str, str]:
374
+ """Return ``(action, decision_reason)`` with fixed precedence (plan Rule 7).
375
+
376
+ (a) human/loaded plan action >
377
+ (b) explicit selection for removal >
378
+ (c) explicit selection for keep (everything not chosen when the user made
379
+ a genuine decision) >
380
+ (d) persistent top-overlay safety default (keep) >
381
+ (e) detector default_remove.
382
+ """
383
+ cid = candidate.id
384
+ if cid in loaded_actions:
385
+ action = loaded_actions[cid]
386
+ if action not in _ACTION_VALUES:
387
+ raise InvalidInputError(
388
+ f"loaded action {action!r} for track {cid} not in {_ACTION_VALUES}"
389
+ )
390
+ return action, f"loaded-plan:{action}"
391
+ if cid in explicit_remove_ids:
392
+ return "remove", "explicit-selection"
393
+ if cid in explicit_keep_ids:
394
+ return "keep", "explicit-keep"
395
+ _x1, y1, _x2, y2 = candidate.bbox
396
+ cy = (y1 + y2) / 2.0
397
+ if cy < _TOP_REGION_FRACTION * height and presence_fraction >= _PERSISTENT_PRESENCE:
398
+ return "keep", "safety:persistent-top-overlay"
399
+ return ("remove" if candidate.default_remove else "keep"), "default-rule"
400
+
401
+
402
+ def _candidate_mask(candidate, frame_shape: tuple[int, int]) -> np.ndarray:
403
+ """Concrete 2D uint8 spatial mask: the candidate's mask, or a filled bbox."""
404
+ h, w = frame_shape
405
+ if getattr(candidate, "mask", None) is not None:
406
+ arr = np.asarray(candidate.mask)
407
+ if arr.ndim == 3:
408
+ arr = arr[:, :, 0]
409
+ return arr.astype(np.uint8)
410
+ x1, y1, x2, y2 = candidate.bbox
411
+ mask = np.zeros((h, w), dtype=np.uint8)
412
+ mask[max(0, y1):y2 + 1, max(0, x1):x2 + 1] = 1
413
+ return mask
414
+
415
+
416
+ def build_wipe_plan(
417
+ candidates: Sequence,
418
+ sample_indices: Sequence[int],
419
+ n_valid: int,
420
+ source: Source,
421
+ frame_shape: tuple[int, int],
422
+ *,
423
+ request: Mapping[str, Any] | None = None,
424
+ explicit_remove_ids: set[str] | None = None,
425
+ explicit_keep_ids: set[str] | None = None,
426
+ loaded_actions: Mapping[str, str] | None = None,
427
+ ) -> WipePlan:
428
+ """Build a validated :class:`WipePlan` from detection outputs.
429
+
430
+ ``candidates`` are duck-typed objects with ``id, type, label, bbox,
431
+ confidence, default_remove, mask`` and (optionally) ``presence_frames`` —
432
+ the real video frame indices where the candidate was present in a sampled
433
+ frame. ``sample_indices`` are the real frame indices of the successful
434
+ samples (same space as ``presence_frames``); ``n_valid`` is the count used
435
+ to normalize ``presence_fraction``.
436
+ """
437
+ height, _width = frame_shape
438
+ frame_count = source.frame_count
439
+ explicit_remove_ids = set(explicit_remove_ids or set())
440
+ explicit_keep_ids = set(explicit_keep_ids or set())
441
+ loaded_actions = dict(loaded_actions or {})
442
+ samples = sorted(int(x) for x in (sample_indices or []))
443
+
444
+ tracks: list[Track] = []
445
+ warnings: list[str] = []
446
+ seen: set[str] = set()
447
+ for c in candidates:
448
+ if c.id in seen:
449
+ raise InvalidInputError(f"Duplicate candidate id: {c.id}")
450
+ seen.add(c.id)
451
+
452
+ presence_frames = set(getattr(c, "presence_frames", []) or [])
453
+ candidate_samples = sorted(set(
454
+ int(x) for x in (getattr(c, "temporal_sample_indices", []) or [])
455
+ ))
456
+ effective_samples = candidate_samples or samples
457
+ effective_n_valid = len(candidate_samples) if candidate_samples else n_valid
458
+ presence_fraction = (
459
+ len(presence_frames) / float(effective_n_valid)
460
+ if effective_n_valid > 0 else 0.0
461
+ )
462
+
463
+ if candidate_samples:
464
+ segs = segments_from_presence(effective_samples, presence_frames, frame_count)
465
+ seg_note = (
466
+ f"{len(segs)} segment(s) from {len(presence_frames)}/"
467
+ f"{effective_n_valid} samples"
468
+ )
469
+ elif presence_frames:
470
+ segs = segments_from_presence(effective_samples, presence_frames, frame_count)
471
+ seg_note = f"{len(segs)} segment(s) from {len(presence_frames)}/{effective_n_valid} samples"
472
+ else:
473
+ segs = [Segment(0, frame_count)] if frame_count > 0 else []
474
+ seg_note = "full-video (no per-frame evidence)"
475
+ warnings.append(
476
+ f"track {c.id} ({c.label}) has no per-frame presence evidence; "
477
+ f"using full-video segment"
478
+ )
479
+
480
+ action, decision = _resolve_action(
481
+ c, presence_fraction, height, explicit_remove_ids, explicit_keep_ids, loaded_actions
482
+ )
483
+ tracks.append(
484
+ Track(
485
+ id=c.id,
486
+ type=str(c.type),
487
+ label=c.label,
488
+ action=action,
489
+ bbox=tuple(int(v) for v in c.bbox),
490
+ confidence=float(c.confidence),
491
+ presence_fraction=presence_fraction,
492
+ decision_reason=f"{decision}; segments: {seg_note}",
493
+ segments=segs,
494
+ mask_key=c.id,
495
+ mask=_candidate_mask(c, frame_shape),
496
+ )
497
+ )
498
+
499
+ temporal = _temporal_resolution(samples, frame_count, source.fps)
500
+ if temporal.max_gap_seconds > _COARSE_GAP_SECONDS:
501
+ warnings.append(
502
+ f"coarse temporal resolution: max sample gap "
503
+ f"{temporal.max_gap_seconds:.2f}s > {_COARSE_GAP_SECONDS}s threshold; "
504
+ f"temporal boundaries may be imprecise"
505
+ )
506
+
507
+ plan = WipePlan(
508
+ kind=PLAN_KIND,
509
+ schema_version=SCHEMA_VERSION,
510
+ source=source,
511
+ request=dict(request or {}),
512
+ temporal_resolution=temporal,
513
+ mask_asset=MaskAsset(filename=MASK_FILENAME, sha256=""),
514
+ tracks=tracks,
515
+ warnings=warnings,
516
+ )
517
+ validate_plan(plan, frame_shape=frame_shape)
518
+ return plan
519
+
520
+
521
+ def build_refined_wipe_plan(
522
+ video_path: str,
523
+ result: Any,
524
+ source: Source,
525
+ *,
526
+ refine: bool,
527
+ request: Mapping[str, Any] | None = None,
528
+ explicit_remove_ids: set[str] | None = None,
529
+ explicit_keep_ids: set[str] | None = None,
530
+ loaded_actions: Mapping[str, str] | None = None,
531
+ progress: Any = None,
532
+ check_cancelled: Any = None,
533
+ ) -> WipePlan:
534
+ """Build one provisional -> refine -> final plan from detection output."""
535
+ kwargs = {
536
+ "request": request,
537
+ "explicit_remove_ids": explicit_remove_ids,
538
+ "explicit_keep_ids": explicit_keep_ids,
539
+ "loaded_actions": loaded_actions,
540
+ }
541
+ provisional = build_wipe_plan(
542
+ result.candidates, result.sample_indices, len(result.sample_indices),
543
+ source, result.frame_shape, **kwargs,
544
+ )
545
+ if not refine:
546
+ return provisional
547
+
548
+ from videoclean.detect import refine_temporal_presence
549
+
550
+ warnings = refine_temporal_presence(
551
+ video_path, result,
552
+ {track.id: track.segments for track in provisional.remove_tracks},
553
+ source.frame_count,
554
+ progress=progress,
555
+ check_cancelled=check_cancelled,
556
+ )
557
+ final = build_wipe_plan(
558
+ result.candidates, result.sample_indices, len(result.sample_indices),
559
+ source, result.frame_shape, **kwargs,
560
+ )
561
+ final.warnings.extend(warnings)
562
+ validate_plan(final, frame_shape=result.frame_shape)
563
+ return final
564
+
565
+
566
+ # ── validation ───────────────────────────────────────────────────────────────
567
+
568
+ def validate_plan(
569
+ plan: WipePlan,
570
+ *,
571
+ frame_shape: tuple[int, int] | None = None,
572
+ require_remove: bool = False,
573
+ ) -> None:
574
+ """Raise :class:`InvalidInputError` on any structural violation."""
575
+ if plan.kind != PLAN_KIND:
576
+ raise InvalidInputError(f"plan.kind must be {PLAN_KIND!r}, got {plan.kind!r}")
577
+ if plan.schema_version != SCHEMA_VERSION:
578
+ raise InvalidInputError(
579
+ f"unsupported schema_version {plan.schema_version} (expected {SCHEMA_VERSION})"
580
+ )
581
+ if plan.mask_asset.filename != MASK_FILENAME:
582
+ raise InvalidInputError(
583
+ f"mask_asset.filename must be {MASK_FILENAME!r}, got {plan.mask_asset.filename!r}"
584
+ )
585
+ _assert_bare_name(plan.mask_asset.filename) # name-only safety check
586
+
587
+ height = plan.source.height
588
+ width = plan.source.width
589
+ frame_count = plan.source.frame_count
590
+ if width <= 0 or height <= 0 or frame_count < 0:
591
+ raise InvalidInputError(
592
+ f"invalid source dims: {width}x{height}@{frame_count}"
593
+ )
594
+ if frame_shape is not None and frame_shape != (height, width):
595
+ raise InvalidInputError(
596
+ f"plan source {height}x{width} disagrees with detection {frame_shape[0]}x{frame_shape[1]}"
597
+ )
598
+
599
+ ids: set[str] = set()
600
+ has_remove = False
601
+ for t in plan.tracks:
602
+ if not t.id:
603
+ raise InvalidInputError("track id must be non-empty")
604
+ if t.id in ids:
605
+ raise InvalidInputError(f"duplicate track id: {t.id}")
606
+ ids.add(t.id)
607
+ if t.action not in _ACTION_VALUES:
608
+ raise InvalidInputError(
609
+ f"track {t.id}: action {t.action!r} not in {_ACTION_VALUES}"
610
+ )
611
+ if len(t.bbox) != 4 or any(int(v) < 0 for v in t.bbox):
612
+ raise InvalidInputError(f"track {t.id}: bbox must be 4 non-negative ints")
613
+ x1, y1, x2, y2 = t.bbox
614
+ if x2 < x1 or y2 < y1:
615
+ raise InvalidInputError(f"track {t.id}: bbox {t.bbox} is inverted")
616
+
617
+ # Execution requires a precise mask on every remove track. A plan read
618
+ # metadata-only (load_masks=False) may carry mask=None for inspection,
619
+ # but it cannot be executed.
620
+ if require_remove and t.action == "remove" and t.mask is None:
621
+ raise InvalidInputError(
622
+ f"track {t.id}: remove track has no precise mask; cannot execute"
623
+ )
624
+ if t.mask is not None:
625
+ arr = np.asarray(t.mask)
626
+ if arr.ndim not in (2, 3):
627
+ raise InvalidInputError(
628
+ f"track {t.id}: mask must be 2D/3D, got shape {arr.shape}"
629
+ )
630
+ if (arr.shape[0], arr.shape[1]) != (height, width):
631
+ raise InvalidInputError(
632
+ f"track {t.id}: mask shape {arr.shape[:2]} != source {height}x{width}"
633
+ )
634
+ if not (np.issubdtype(arr.dtype, np.integer) or np.issubdtype(arr.dtype, np.bool_)):
635
+ raise InvalidInputError(
636
+ f"track {t.id}: mask dtype {arr.dtype} must be integer/bool"
637
+ )
638
+
639
+ prev_end = 0
640
+ for seg in t.segments:
641
+ if not (0 <= seg.start < seg.end <= frame_count):
642
+ raise InvalidInputError(
643
+ f"track {t.id}: segment [{seg.start},{seg.end}) violates "
644
+ f"0<=start<end<={frame_count}"
645
+ )
646
+ if seg.start < prev_end:
647
+ raise InvalidInputError(
648
+ f"track {t.id}: segments must be sorted and non-overlapping"
649
+ )
650
+ prev_end = seg.end
651
+ if t.action == "remove":
652
+ has_remove = True
653
+
654
+ if require_remove and not has_remove:
655
+ raise InvalidInputError("plan has no remove track; nothing to inpaint")
656
+
657
+
658
+ # ── serialization ────────────────────────────────────────────────────────────
659
+
660
+ def save_wipe_plan(plan: WipePlan, output_dir: str) -> tuple[str, str]:
661
+ """Write ``wipe_plan.json`` + ``wipe_plan_masks.npz`` side-by-side.
662
+
663
+ Returns ``(json_path, npz_path)``. Masks are stored as raw ``uint8``
664
+ arrays keyed by ``track.mask_key`` (sorted for determinism). The NPZ
665
+ SHA-256 is computed after writing and embedded in the JSON.
666
+ """
667
+ os.makedirs(output_dir, exist_ok=True)
668
+ json_path = os.path.join(output_dir, JSON_FILENAME)
669
+ npz_path = _child_path(output_dir, plan.mask_asset.filename)
670
+
671
+ masks: dict[str, np.ndarray] = {}
672
+ for t in sorted(plan.tracks, key=lambda x: x.id):
673
+ if t.mask is None:
674
+ raise InvalidInputError(f"track {t.id} has no mask to save")
675
+ arr = np.asarray(t.mask)
676
+ if arr.ndim == 3:
677
+ arr = arr[:, :, 0]
678
+ masks[t.mask_key] = arr.astype(np.uint8)
679
+ np.savez_compressed(npz_path, **masks)
680
+
681
+ plan.mask_asset = MaskAsset(
682
+ filename=plan.mask_asset.filename, sha256=_sha256_file(npz_path)
683
+ )
684
+ with open(json_path, "w", encoding="utf-8") as fh:
685
+ json.dump(plan.to_dict(), fh, indent=2, sort_keys=True)
686
+ fh.write("\n")
687
+ return json_path, npz_path
688
+
689
+
690
+ def load_wipe_plan(
691
+ plan_path: str,
692
+ *,
693
+ video_path: str | None = None,
694
+ load_masks: bool = True,
695
+ ) -> WipePlan:
696
+ """Load and validate a plan from ``wipe_plan.json`` (+ sidecar NPZ).
697
+
698
+ With ``video_path`` set, the source SHA-256/width/height/frame_count are
699
+ re-derived and must match (executing against a different video is
700
+ rejected); ``require_remove`` is then enforced. Masks are loaded with
701
+ ``allow_pickle=False``.
702
+ """
703
+ plan_path = os.path.realpath(plan_path)
704
+ if not os.path.isfile(plan_path):
705
+ raise InvalidInputError(f"plan not found: {plan_path}")
706
+ plan_dir = os.path.dirname(plan_path)
707
+ with open(plan_path, "r", encoding="utf-8") as fh:
708
+ data = json.load(fh)
709
+ try:
710
+ plan = WipePlan.from_dict(data)
711
+ except KeyError as exc:
712
+ raise InvalidInputError(f"plan JSON missing key: {exc}") from exc
713
+
714
+ npz_path = _child_path(plan_dir, plan.mask_asset.filename)
715
+ if not os.path.isfile(npz_path):
716
+ raise InvalidInputError(f"mask asset not found: {plan.mask_asset.filename}")
717
+ actual_sha = _sha256_file(npz_path)
718
+ if actual_sha != plan.mask_asset.sha256:
719
+ raise InvalidInputError("mask_asset sha256 mismatch (NPZ modified or corrupted)")
720
+
721
+ if video_path is not None:
722
+ actual = compute_source(video_path)
723
+ if actual.sha256 != plan.source.sha256:
724
+ raise InvalidInputError(
725
+ "source sha256 mismatch: plan is bound to a different video"
726
+ )
727
+ if (actual.width, actual.height, actual.frame_count) != (
728
+ plan.source.width,
729
+ plan.source.height,
730
+ plan.source.frame_count,
731
+ ):
732
+ raise InvalidInputError("source width/height/frame_count mismatch")
733
+
734
+ if load_masks:
735
+ with np.load(npz_path, allow_pickle=False) as npz:
736
+ available = set(npz.files)
737
+ for t in plan.tracks:
738
+ if t.mask_key in available:
739
+ t.mask = npz[t.mask_key]
740
+ elif t.mask is None:
741
+ raise InvalidInputError(
742
+ f"mask key {t.mask_key!r} not found in NPZ"
743
+ )
744
+
745
+ validate_plan(plan, require_remove=video_path is not None)
746
+ return plan
747
+
748
+
749
+ def is_temporal(plan: WipePlan) -> bool:
750
+ """True if any remove track is not active on the entire video.
751
+
752
+ File-based inpainters (external command, ProPainter) consume one static
753
+ mask PNG and cannot honor temporal segments; the engine uses this to
754
+ reject such plans instead of silently flattening them.
755
+ """
756
+ frame_count = plan.source.frame_count
757
+ for t in plan.remove_tracks:
758
+ if not (len(t.segments) == 1 and t.segments[0] == Segment(0, frame_count)):
759
+ return True
760
+ return False
761
+
762
+
763
+ def predicted_mask_at(plan: WipePlan, frame_index: int) -> np.ndarray:
764
+ """Boolean ``(H, W)`` remove-prediction mask at *frame_index*.
765
+
766
+ Union of every remove track whose segments contain *frame_index*. This is
767
+ the per-frame prediction a temporal plan makes; the fact-baseline evaluator
768
+ uses it instead of replaying one static mask on every annotated frame.
769
+ """
770
+ height, width = plan.source.height, plan.source.width
771
+ mask = np.zeros((height, width), dtype=bool)
772
+ for t in plan.remove_tracks:
773
+ if any(s.start <= frame_index < s.end for s in t.segments) and t.mask is not None:
774
+ arr = np.asarray(t.mask)
775
+ if arr.ndim == 3:
776
+ arr = arr[:, :, 0]
777
+ mask |= arr.astype(bool)
778
+ return mask
779
+
780
+
781
+ def remove_union_mask(plan: WipePlan) -> np.ndarray:
782
+ """Boolean ``(H, W)`` spatial union of all remove tracks (time-independent)."""
783
+ height, width = plan.source.height, plan.source.width
784
+ mask = np.zeros((height, width), dtype=bool)
785
+ for t in plan.remove_tracks:
786
+ if t.mask is not None:
787
+ arr = np.asarray(t.mask)
788
+ if arr.ndim == 3:
789
+ arr = arr[:, :, 0]
790
+ mask |= arr.astype(bool)
791
+ return mask
src/videoclean/tasks/__init__.py ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ from videoclean.tasks.base import BaseTask, read_frame_info, read_mask, validate_mask_shape
2
+ from videoclean.tasks.detext import DetextTask
3
+ __all__ = ["BaseTask", "DetextTask", "read_frame_info", "read_mask", "validate_mask_shape"]
src/videoclean/tasks/__pycache__/__init__.cpython-314.pyc ADDED
Binary file (375 Bytes). View file
 
src/videoclean/tasks/__pycache__/base.cpython-314.pyc ADDED
Binary file (4.14 kB). View file
 
src/videoclean/tasks/__pycache__/detext.cpython-314.pyc ADDED
Binary file (2.47 kB). View file
 
src/videoclean/tasks/base.py ADDED
@@ -0,0 +1,46 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Video metadata and mask helpers."""
2
+ import cv2
3
+
4
+
5
+ def read_frame_info(video_path: str):
6
+ reader = cv2.VideoCapture(video_path)
7
+ if not reader.isOpened():
8
+ raise ValueError(f"Cannot open video: {video_path}")
9
+ return reader, {
10
+ "W_ori": int(reader.get(cv2.CAP_PROP_FRAME_WIDTH) + 0.5),
11
+ "H_ori": int(reader.get(cv2.CAP_PROP_FRAME_HEIGHT) + 0.5),
12
+ "fps": reader.get(cv2.CAP_PROP_FPS) or 24.0,
13
+ "len": int(reader.get(cv2.CAP_PROP_FRAME_COUNT) + 0.5),
14
+ }
15
+
16
+
17
+ def read_mask(path: str):
18
+ img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
19
+ if img is None:
20
+ raise ValueError(f"Cannot read mask image: {path}")
21
+ _, img = cv2.threshold(img, 127, 1, cv2.THRESH_BINARY)
22
+ return img[:, :, None]
23
+
24
+
25
+ def validate_mask_shape(mask, frame_info: dict) -> None:
26
+ expected = (frame_info["H_ori"], frame_info["W_ori"])
27
+ actual = mask.shape[:2]
28
+ if actual != expected:
29
+ raise ValueError(f"Mask shape {actual[1]}x{actual[0]} does not match video shape {expected[1]}x{expected[0]}")
30
+
31
+
32
+ class BaseTask:
33
+ def __init__(self, gap: int = 200, dual: bool = False):
34
+ self.gap = gap
35
+ self.dual = dual
36
+ self.inpainter = None
37
+ self._bm = None
38
+ self.feather_radius = 0
39
+
40
+ def process_video(self, reader, frame_info, mask, output_dir: str, video_path: str = "", progress=None) -> str:
41
+ raise NotImplementedError
42
+
43
+ def cleanup(self):
44
+ if self.inpainter is not None:
45
+ self.inpainter.cleanup()
46
+ self.inpainter = None
src/videoclean/tasks/detext.py ADDED
@@ -0,0 +1,38 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Subtitle removal task — delegates inpainting to an Inpainter."""
2
+ from videoclean.tasks.base import BaseTask
3
+
4
+
5
+ class DetextTask(BaseTask):
6
+ """Remove hardcoded subtitles from video.
7
+
8
+ The inpainting loop lives in the OpenCV inpainter injected by WipeEngine.
9
+ This task only assembles the :class:`InpaintJob` from
10
+ the prepared reader/mask and returns the output path.
11
+ """
12
+
13
+ def process_video(self, reader, frame_info, mask, output_dir: str,
14
+ video_path: str = "", progress=None) -> str:
15
+ from videoclean.inpainters.base import InpaintJob
16
+
17
+ metrics = self._bm.get("timing", {}) if isinstance(self._bm, dict) else {}
18
+ job = InpaintJob(
19
+ video_path=video_path,
20
+ mask=mask,
21
+ output_dir=output_dir,
22
+ fps=frame_info["fps"],
23
+ frame_count=frame_info["len"],
24
+ width=frame_info["W_ori"],
25
+ height=frame_info["H_ori"],
26
+ dual=self.dual,
27
+ gap=self.gap,
28
+ output_suffix=getattr(self, "output_suffix", "detext"),
29
+ reader=reader,
30
+ progress=progress,
31
+ metrics=metrics,
32
+ mask_path=getattr(self, "mask_path", None),
33
+ feather_radius=getattr(self, "feather_radius", 0),
34
+ frame_mask=getattr(self, "frame_mask", None),
35
+ )
36
+ outcome = self.inpainter.inpaint(job)
37
+ self.backend_label = outcome.backend
38
+ return outcome.output_path
src/videoclean/weights.py ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Cache and download the DBNet detector weight."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ import urllib.request
6
+
7
+ from tqdm import tqdm
8
+
9
+ _WEIGHTS_DIR = os.environ.get("VIDEOCLEAN_WEIGHTS_DIR", os.path.expanduser("~/.videoclean/weights"))
10
+ _WEIGHT_BASE = "https://huggingface.co/stevenlearns/videoclean-detector/resolve"
11
+ _MANUAL_DOWNLOAD_MSG = (
12
+ "Automatic download failed. Download the detector weight manually from:\n"
13
+ " https://huggingface.co/stevenlearns/videoclean-detector\n"
14
+ "Place it in ~/.videoclean/weights/ or set VIDEOCLEAN_WEIGHTS_DIR."
15
+ )
16
+
17
+
18
+ def get_weights_dir() -> str:
19
+ os.makedirs(_WEIGHTS_DIR, exist_ok=True)
20
+ return _WEIGHTS_DIR
21
+
22
+
23
+ def ensure_weight(filename: str, version: str = "main") -> str:
24
+ """Return the detector weight path, downloading it when absent."""
25
+ if filename != "ppocrv5_det_mob.onnx":
26
+ raise ValueError(f"Unsupported detector weight: {filename}")
27
+ local_path = os.path.join(get_weights_dir(), filename)
28
+ if os.path.isfile(local_path):
29
+ return local_path
30
+ url = f"{_WEIGHT_BASE}/{version}/{filename}"
31
+ print(f"Downloading {filename} from {url}")
32
+ try:
33
+ _download_with_progress(url, local_path)
34
+ except Exception as exc:
35
+ if os.path.exists(local_path):
36
+ os.remove(local_path)
37
+ raise RuntimeError(f"Failed to download {filename}: {exc}\n{_MANUAL_DOWNLOAD_MSG}") from exc
38
+ return local_path
39
+
40
+
41
+ def _download_with_progress(url: str, dest: str) -> None:
42
+ tmp_path = dest + ".tmp"
43
+
44
+ class _Progress(tqdm):
45
+ def update_to(self, blocks: int = 1, block_size: int = 1, total: int | None = None):
46
+ if total is not None:
47
+ self.total = total
48
+ self.update(blocks * block_size - self.n)
49
+
50
+ with _Progress(unit="B", unit_scale=True, desc=os.path.basename(dest)) as progress:
51
+ urllib.request.urlretrieve(url, tmp_path, reporthook=progress.update_to)
52
+ os.replace(tmp_path, dest)
tests/__pycache__/test_opencv_inpainter.cpython-314-pytest-9.1.1.pyc ADDED
Binary file (12.2 kB). View file
 
tests/test_opencv_inpainter.py ADDED
@@ -0,0 +1,62 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import cv2
2
+ import numpy as np
3
+ import pytest
4
+
5
+ from videoclean.cli import _build_parser
6
+ from videoclean.inpainters import OpenCVInpainter, get_registry
7
+ from videoclean.inpainters.base import InpaintJob
8
+
9
+
10
+ def _video(path, frames=4, width=96, height=64):
11
+ writer = cv2.VideoWriter(str(path), cv2.VideoWriter_fourcc(*"mp4v"), 4, (width, height))
12
+ for i in range(frames):
13
+ frame = np.full((height, width, 3), 30 + i * 5, dtype=np.uint8)
14
+ cv2.rectangle(frame, (60, 20), (78, 30), (255, 255, 255), -1)
15
+ writer.write(frame)
16
+ writer.release()
17
+
18
+
19
+ def test_registry_and_cli_options():
20
+ assert "opencv" in get_registry().names()
21
+ assert isinstance(get_registry().create("opencv", method="ns"), OpenCVInpainter)
22
+ args = _build_parser().parse_args([
23
+ "clean", "input.mp4", "--inpaint-method", "ns",
24
+ "--inpaint-radius", "5", "--inpaint-dilate", "2",
25
+ ])
26
+ assert (args.inpaint_method, args.inpaint_radius, args.inpaint_dilate) == (
27
+ "ns", 5.0, 2,
28
+ )
29
+
30
+ def test_mask_validation_and_normalization(tmp_path):
31
+ inpainter = OpenCVInpainter()
32
+ base = dict(video_path="x.mp4", output_dir=str(tmp_path), fps=4, frame_count=1, width=8, height=6)
33
+ with pytest.raises(ValueError, match="no inpaintable"):
34
+ inpainter._prepare_mask(InpaintJob(mask=np.zeros((6, 8), np.float32), **base))
35
+ mask = inpainter._prepare_mask(InpaintJob(mask=np.eye(6, 8, dtype=np.float32)[:, :, None], **base))
36
+ assert mask.dtype == np.uint8
37
+ assert set(np.unique(mask)) <= {0, 255}
38
+
39
+
40
+ def test_inpaints_all_frames_and_reports_progress(tmp_path):
41
+ source = tmp_path / "source.mp4"
42
+ _video(source)
43
+ reader = cv2.VideoCapture(str(source))
44
+ mask = np.zeros((64, 96, 1), dtype=np.float32)
45
+ mask[20:31, 60:79] = 1
46
+ progress = []
47
+ metrics = {}
48
+ outcome = OpenCVInpainter(radius=3, dilate=1).inpaint(InpaintJob(
49
+ video_path=str(source), mask=mask, output_dir=str(tmp_path), fps=4,
50
+ frame_count=4, width=96, height=64, reader=reader, progress=lambda d, t: progress.append((d, t)), metrics=metrics,
51
+ output_suffix="clean",
52
+ ))
53
+ reader.release()
54
+ assert outcome.backend == "opencv"
55
+ assert progress[-1] == (4, 4)
56
+ assert "inpainting_s" in metrics
57
+ output = cv2.VideoCapture(outcome.output_path)
58
+ count = 0
59
+ while output.read()[0]:
60
+ count += 1
61
+ output.release()
62
+ assert count == 4
vpipe ADDED
@@ -0,0 +1,64 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Batch front-end for videoclean."""
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import shutil
7
+ import subprocess
8
+ import sys
9
+ from pathlib import Path
10
+
11
+ VIDEO_EXTENSIONS = {".mp4", ".mkv", ".mov", ".m4v", ".avi", ".webm"}
12
+
13
+
14
+ def main() -> int:
15
+ parser = argparse.ArgumentParser(description="Batch-clean videos with videoclean")
16
+ parser.add_argument("source", help="Video file or directory")
17
+ parser.add_argument("-o", "--output", help="Output directory")
18
+ parser.add_argument("--clean", action="store_true", help="Remove detected overlays")
19
+ parser.add_argument("-y", "--yes", action="store_true", help="Run without confirmation")
20
+ parser.add_argument("--detect-mode", choices=["fast", "balanced", "sensitive"], default="balanced")
21
+ parser.add_argument("--inpaint-method", choices=["telea", "ns"], default="telea")
22
+ parser.add_argument("--inpaint-radius", type=float, default=3.0)
23
+ parser.add_argument("--inpaint-dilate", type=int, default=0)
24
+ args = parser.parse_args()
25
+
26
+ source = Path(args.source).expanduser().resolve()
27
+ if source.is_file():
28
+ videos = [source]
29
+ elif source.is_dir():
30
+ videos = sorted(path for path in source.iterdir() if path.suffix.lower() in VIDEO_EXTENSIONS)
31
+ else:
32
+ parser.error(f"source does not exist: {source}")
33
+ if not videos:
34
+ parser.error(f"no videos found in {source}")
35
+
36
+ output = Path(args.output).expanduser().resolve() if args.output else source.parent / f"{source.stem}_processed"
37
+ output.mkdir(parents=True, exist_ok=True)
38
+ python = Path(__file__).resolve().parent / ".venv" / "bin" / "python"
39
+ if not python.exists():
40
+ python = Path(sys.executable)
41
+
42
+ for video in videos:
43
+ destination = output / f"{video.stem}.mp4"
44
+ if not args.clean:
45
+ shutil.copy2(video, destination)
46
+ continue
47
+ command = [
48
+ str(python), "-m", "videoclean.cli", "clean", str(video),
49
+ "-o", str(output), "--detect-mode", args.detect_mode,
50
+ "--inpaint-method", args.inpaint_method,
51
+ "--inpaint-radius", str(args.inpaint_radius),
52
+ "--inpaint-dilate", str(args.inpaint_dilate),
53
+ ]
54
+ result = subprocess.run(command)
55
+ if result.returncode:
56
+ return result.returncode
57
+ generated = output / f"{video.stem}_clean.mp4"
58
+ if generated.exists() and generated != destination:
59
+ generated.replace(destination)
60
+ return 0
61
+
62
+
63
+ if __name__ == "__main__":
64
+ raise SystemExit(main())