Welcome to pycaps discussions!

[francozanardi]

👋 Welcome to the PyCaps Community!

We’re using GitHub Discussions as a place to build a community around pycaps. This is an open and inclusive space where you can:

• 💬 Ask questions about using pycaps.
• 🎨 Share ideas for subtitle styles, animations, or templates.
• 🐛 Talk about bugs or unexpected behaviors.
• 💡 Suggest improvements or integrations.
• 🤝 Connect with other creators and collaborators.

To get started, feel free to introduce yourself below and tell us how you're using or planning to use pycaps. We’d love to hear from you! 🙌

---

New here?
Check out the README to learn what pycaps is all about.

🚀 Thanks for being part of the community!

[normuradov]

Hi Franco,

First off, thank you for creating such a fantastic and powerful library! pycaps is incredibly useful for anyone working on automated video generation for social media.

As I've been studying the library's architecture for my own project, I have a key question about the rendering mechanism.

My understanding is that the library brilliantly generates highly complex .ass files and then uses FFmpeg's native ASS/SSA filter to burn the subtitles and effects directly onto the video. This would mean it operates without any browser-based rendering (e.g., using a headless browser to render HTML/CSS and capture the output).

Could you please confirm if this understanding is correct? Are all the dynamic effects we see achieved exclusively through the FFmpeg + .ass pipeline?

I'm asking because this approach seems significantly more resource-efficient and performant compared to alternatives like MoviePy or browser-based solutions. If pycaps relies entirely on the .ass format, it would be a huge advantage for large-scale projects where performance is critical.

Any clarification you could provide would be hugely appreciated.

Thanks again for your amazing work!

[francozanardi]

Hey @normuradov. Thanks for your kind words :)

My understanding is that the library brilliantly generates highly complex .ass files and then uses FFmpeg's native ASS/SSA filter to burn the subtitles and effects directly onto the video. This would mean it operates without any browser-based rendering (e.g., using a headless browser to render HTML/CSS and capture the output).

Pycaps allows defining the styles the subtitles using CSS, providing some predefined classes, such as word-being-narrated or word-already-narrated. Then, for the animations it uses opencv + numpy, to apply transformation to a pixel-level. Finally, it uses ffmpeg to render the final video (it doesn't use moviepy, since it was really slow).

How does Pycaps render the CSS provided?

It has two different renderers:

• CssSubtitleRenderer: it uses a headless browser to render the CSS, and the take the screenshots for each word. This is the default renderer, and the templates were created for this specific renderer.
• PictexSubtitleRenderer: it doesn't use a browser, instead it uses a library called html2pic, which is based on pictex, which is based on skia. It's much faster than using a headless browser. However, it only supports a small subset of CSS, but it's fine for most of the use cases. If you use this renderer, you will probably need to update the CSS from the templates, since the generated images could be a little bit different respect to the browser renderer.

If you need performance, and you want to use the PictexSubtitleRenderer, you could change it in the CapsPipeline:

- self._renderer: SubtitleRenderer = CssSubtitleRenderer()
+ self._renderer: SubtitleRenderer = PictexSubtitleRenderer()

Finally, you can find the templates in the following path: src/pycaps/template/preeset/.

For example, for the hype template, you have this css, and this config file. In the JSON file, you can set some things like animations, or other configurations.

[normuradov]

Hello,

In our project, we are using Google Cloud Speech-to-Text v2 for transcription due to specific project requirements. We would love to use pycaps for its powerful rendering and animation capabilities.

We are looking for the best and cleanest way to integrate our existing transcription data into the pycaps pipeline, effectively bypassing the built-in Whisper transcriber.

Thank you for your time and any guidance you can provide

[francozanardi]

Hello @normuradov :)

PyCaps is highly configurable. The default transcriber is Whisper, but it can be easily replaced.

How are you using PyCaps? Are you using it from the command line interface? or via code as a library?

The transcriber is initialized in the CapsPipeline, here: https://github.com/francozanardi/pycaps/blob/main/src/pycaps/pipeline/caps_pipeline.py#L24

How to create a new audio transcriber

To create a new audio transcriber behavior, you must create a new file extending the abstract AudioTranscriber class. For example, PyCaps includes two different audio transcriber implementations:

• Whisper
• Google Cloud Speech-to-Text V1

So, you can take them as reference and create a new one using the Google Cloud Speech-to-Text V2.

How to replace the default audio transcriber

If you are using PyCaps as a library (setting the things in the code), you can change the audio transcriber using the CapsPipelineBuilder.with_custom_audio_transcriber() method.

If you want to replace the default audio transcriber in all the cases, the easiest approach could be changing it in the CapsPipeline.

Let me know if you need anything else!