stockclip

Search several free stock-video banks at once, and keep only the clips you can actually use.

One command searches Pixabay, Pexels and Wikimedia Commons together, drops anything that would look soft in a 1080p frame, drops any licence that would contaminate your finished work, and writes the attribution you owe.

$ stockclip --sources commons -n 8 search "kidney" --need-seconds 9.5

"kidney" - 8 result(s) read, 4 kept after filters

  source    ref                                  len resolution  licence          title
  * = the searched word is in the FILE TITLE (100% relevance, measured)
  *commons  File:Non-invasive-Differentiation-   15s  1984x992   CC BY 4.0        covers
  *commons  File:Human Kidney Ultrasound Scan.    7s  1920x1080  CC BY 4.0        TOO SHORT
  *commons  File:Inspection of the Ongoing Con  139s  1920x1080  Public domain    needs cutting
  *commons  File:Visit to the National Kidney   687s  1920x1080  Public domain    needs cutting

  4 dropped: under 1920 wide, or a share-alike / restricted licence.

Every stock-video search tool queries one bank. Each bank is strong somewhere and useless elsewhere, and you only find that out after wasting an afternoon.

These numbers come from reading, by hand, every result of 20 queries from a health video channel's editorial line:

So the split of roles is not an opinion:

• anatomical or scientific mechanism goes to Commons first
• lifestyle and documentary b-roll goes to Pexels first
• the clean generic shot goes to Pixabay, which is the best tagged

Width at least 1920. A 1280x720 clip inside a 1920x1080 frame is upscaled 1.5x and visibly soft. On Commons only 8% of matching files clear that bar, so the filter is pushed to the server: without it you download twelve clips to keep one.

No share-alike, no non-commercial, no no-derivatives. 11% of Commons medical video is CC BY-SA, and one such clip forces your whole finished work under the same licence. The refusal happens at selection time, not at edit time when it is too late.

The licence test splits into tokens rather than searching substrings. CC BY-SA 4.0 contains neither a space-delimited sa nor a -sa suffix, and the first version of that test accepted the three licences it was written to refuse. Run stockclip selftest and it proves both filters on rejected cases, not only on cases that pass.

Commons full-text search reads the entire file page, so liver first returned a 621-second Korean drama. Measured over six terms, restricting to the title changes everything:

100% relevance, far less volume. So stockclip runs both passes and marks the title matches with a star, rather than making you choose between precision and material.

pip install stockclip

Or clone and run the single file directly. It needs Python 3.8 or newer and nothing else. python-dotenv is optional, ffmpeg is only needed for --cut.

Commons needs no key. The other banks do, and all of them are free:

Put them in the environment, or in a .env file in the working directory. See .env.example.

A bank with no key does not return "zero results", it reports that it was not queried. Confusing the two makes a subject look unfilmable when in fact nobody looked.

Search one term. --need-seconds is the length of the shot you need, and each result is labelled covers, TOO SHORT or needs cutting.

stockclip search "microscope laboratory" --need-seconds 9.5

Check whether a topic is filmable at all, before writing a script around it.

stockclip topic "liver, fatty liver, alcohol, detox" --need 6

It prints usable clips per term per bank and a verdict. Terms under three clips are named, so you know which parts of your subject will have to be carried by something other than footage. Treat the total as a ceiling: count the Pexels column at one third, because Pexels fills in.

Take a clip. It downloads, optionally cuts with ffmpeg, and writes a licence card next to the file recording source, licence, author and page.

stockclip take commons:File:Human_Kidney_Ultrasound_Scan.webm \
  --out ./clips --name kidney_scan --cut 9.5

Print what you owe. 89% of the Commons medical pool is CC BY, which must be credited wherever you publish. This reads the licence cards in a directory and prints the block to paste.

stockclip credits --out ./clips

• Openverse has no video endpoint at all: /v1/video/ and /v1/videos/ both answer 404. It serves images and audio only.
• Internet Archive returns 4429 results for "kidney"; filtering to Creative Commons leaves 154 whose top hits are a kitten compilation and a podcast.
• Coverr is wired in but off by default: 64 clips read, 2 relevant (3%), and 14 queries out of 20 returned nothing. "liver" returns rivers. Pass --sources coverr when you want daily-life b-roll, which is what it is good at.

MIT. Extracted from an automated video production pipeline, where these filters were written one defect at a time.