Metadata-Version: 2.4
Name: framestoryx
Version: 0.1.1
Summary: An extended version of FrameStory, for creating video descriptions.
Project-URL: Homepage, https://github.com/fossiaorg/framestoryx
Author-email: Keerthana Rajesh Kumar <grittypuffy@riseup.net>, Eugene Evstafev <chigwel@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Requires-Dist: numpy>=2.3.5
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: pillow>=12.0.0
Requires-Dist: requests>=2.32.5
Requires-Dist: torch>=2.9.1
Requires-Dist: torchvision>=0.24.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: transformers>=4.57.3
Description-Content-Type: text/markdown

[![PyPI version](https://badge.fury.io/py/framestoryx.svg)](https://badge.fury.io/py/framestoryx)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/framestoryx)](https://pepy.tech/project/framestoryx)

# framestory

`framestoryx` is a successor to [FrameStory](https://github.com/chigwell/frame_story/) for better compatibility with modern Python tooling. Leveraging state-of-the-art machine learning models, it can provide detailed descriptions of video content, making it a powerful tool for content analysis, accessibility, and summarization.

## Installation

To install `framestoryx`, you can use pip:

```bash
pip install framestoryx
```

## Usage

Using `framestoryx` is straightforward. Below are examples demonstrating how to extract and describe significant frames from videos with various parameters.

### Describing Video by URL

```python
from framestoryx.video_describer import VideoDescriber

video_url = "https://example.com/video.mp4"
describer = VideoDescriber(show_progress=True)
descriptions = describer.get_video_descriptions(video_url=video_url)
print(descriptions)
```

### Describing Video from Local Path

```python
video_path = "/path/to/your/video.mp4"
describer = VideoDescriber(show_progress=True, max_tokens=50)
descriptions = describer.get_video_descriptions(video_path=video_path)
print(descriptions)
```

### Customizing Extraction Threshold

The `extract_significant_frames` method allows you to customize the threshold for what constitutes a "significant" change between frames.

```python
video_url = "https://example.com/video.mp4"
describer = VideoDescriber(threshold=25000)
descriptions = describer.get_video_descriptions(video_url=video_url)
print(descriptions)
```

These examples demonstrate the versatility of `frame_story` in processing videos from different sources and with various levels of detail in descriptions.

## Features

- Extraction of significant frames from videos for detailed analysis.
- Generation of descriptive text for each significant frame using state-of-the-art image captioning models.
- Support for videos from URLs or local file paths.
- Customizable settings for progress display, description length, and frame extraction threshold.
- Easy to integrate into Python projects for content analysis, summarization, and accessibility applications.

## Contributing

We welcome contributions, be it issues or feature requests.

Feel free to check the [issues page](https://codeberg.org/fossiaorg/framestoryx/issues) and adhere to our [contributing guidelines](https://fossia.org/resources/contributing) before submitting a pull request.

## License

This project is licensed under the [MIT License](https://choosealicense.com/licenses/mit/).
