PySceneDetect

PySceneDetect copied to clipboard

Unlike the CLI documentation, the current API documentation, while well organized, does a poor job of showing new users where to start and how to begin. Specifically, the current (single) API usage example is very large and does a poor job of explaining the API step-by-step, and includes a StatsManager (which makes it longer than necessary). To improve the documentation:

• rewrite a smaller, most bare bones example in the manual, ~~and makes sure it's actually in the spot it should be (and not one more link deeper...)~~ - done
• replace the example in the SceneManager documentation with this one
• move the existing example to the bottom of the SceneManager page, or move it entirely to the StatsManager page
• use the new barebones example to write a more free flowing, almost step-by-step introduction to the API similar to Pydub, specifically for the Documentation and Github Readme (also will help distinguish them from the manual)
• now do the same for the CLI as well
• add a tutorial showing how to create a new detector

Also, start removing more pages from the website and transitioning them to the manual. This might also mean, eventually, that docs/ can be renamed to site/, and manual/ to docs/.

From this, I realized the API would be even cleaner if I made the base_timecode argument optional when calling get_scenes() on a SceneManager, thus I created #173 to track that work.

In the meantime, the existing documentation examples in master have now been much improved.

What I'm personally missing in the docs is how to invoke ffmpeg/mkvmerge to split the video up into the detected scenes. I think developers would appreciate a "recipe" for exactly that action.

The Documentation for the CLI fulfills this scenario completely.

@Zenahr good point - I'll have to figure out a good spot for it (if not just directly in the Video Splitting section), or perhaps should make a new section for small code snippets. My initial thought is to make sure every major page in the API section has some examples on it though, rather than creating an explicit page full of snippets. Thoughts?

I'd personally lean towards a dedicated traditional "recipes" section with short code for specific goals.

This also functions as a Getting Started guide for programmers as well as get familar with basic API usage without being bogged down by many lines of documentation to read.

"Recipes" are a thing in technical documentation so maybe look up a couple examples to get inspiration?

It's awesome to see a project valueing the docs so much!

Thanks for the feedback, definitely will be looking into adding this.

I was also thinking to see if the examples have common code, and if so, to refactor them into high-level functions in the top level scenedetect package, e.g. the find_scenes() method in the quickstart. I'll leave that for the end though, as I'm still unsure if that's unnecessary abstraction or maybe oversimplifying things.

yeah it's not easy to define the API but I think we'll get lots of input for those kinds of things by the community anyway. A non-intuitive API with straight-forward docs is better than a somewhat intuitive API with no docs imo.

Need to add all future recipes as unit tests as well to ensure they are stable and work as expected. Some of the tests may also serve as useful recipes as-is.

(I don't have enough capacity to tackle this anytime soon unfortunately, so have added some new tags - any contributions are most welcome! :)

Hopefully the new v0.6 API documentation is much better in this regard, and an example of video splitting is included in the quickstart now: http://scenedetect.com/projects/Manual/en/latest/api.html#quickstart

There is also now a specific test file containing many common use cases for quick reference: https://github.com/Breakthrough/PySceneDetect/blob/master/tests/test_api.py

Happy to hear any feedback or suggestions on the new docs! :)