Metadata-Version: 2.1
Name: traa
Version: 0.1.5
Summary: Python bindings for the TRAA (To Record Anything Anywhere) library - a high-performance, cross-platform solution for screen capture, window enumeration, and desktop recording. Supports Windows, macOS, and Linux with a clean, Pythonic API.
Home-page: https://github.com/opentraa/traa-py
Author: opentraa
Author-email: Sylar <peilinok@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2024, opentraa
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/opentraa/traa-py
Project-URL: Issues, https://github.com/opentraa/traa-py/issues
Keywords: Screen Capturer,Snapshot,Desktop Capturer
Platform: Windows
Platform: Linux
Platform: macOS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cffi>=1.17.1
Requires-Dist: numpy>=2.2.3
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: wheel>=0.37.0; extra == "dev"

# TRAA Python Bindings

Python bindings for the TRAA (To Record Anything Anywhere) library - a high-performance, cross-platform solution for screen capture, window enumeration, and desktop recording. Supports Windows, macOS, and Linux with a clean, Pythonic API.

## Features

- Screen and window enumeration with filtering options
- High-performance screen capture
- Support for multiple displays and windows
- Thumbnail and icon capture
- Cross-platform compatibility (Windows, macOS, Linux)

## Installation

```bash
pip install traa
```

## Quick Start

```python
from traa import Size, ScreenSourceFlags, enum_screen_sources, create_snapshot
from PIL import Image

# Enumerate screen sources
sources = enum_screen_sources(
    thumbnail_size=Size(160, 120),  # Optional: Get thumbnails
    icon_size=Size(32, 32),        # Optional: Get icons
    external_flags=ScreenSourceFlags.NONE  # Use default enumeration behavior
)

# Print available sources
for source in sources:
    print(f"Found source: {source}")
    
    # Save thumbnail if available
    if source.thumbnail_data is not None:
        Image.fromarray(source.thumbnail_data).save(f"thumb_{source.id}.png")
    
    # Save icon if available
    if source.icon_data is not None:
        Image.fromarray(source.icon_data).save(f"icon_{source.id}.png")

# Capture from the first source
if sources:
    # Capture at Full HD resolution
    image, actual_size = create_snapshot(sources[0].id, Size(1920, 1080))
    
    # Determine image mode based on shape
    mode = "RGB" if len(image.shape) == 3 and image.shape[2] == 3 else \
           "RGBA" if len(image.shape) == 3 and image.shape[2] == 4 else "L"
    
    # Save the snapshot
    Image.fromarray(image, mode=mode).save("snapshot.png")
    print(f"Captured image size: {actual_size}")
```

## API Reference

### Functions

#### `enum_screen_sources(icon_size: Optional[Size] = None, thumbnail_size: Optional[Size] = None, external_flags: ScreenSourceFlags = ScreenSourceFlags.NONE) -> List[ScreenSourceInfo]`

Enumerates available screen sources (displays and windows).

- `icon_size`: Optional size for source icons
- `thumbnail_size`: Optional size for source thumbnails
- `external_flags`: Flags to control enumeration behavior
- Returns: List of `ScreenSourceInfo` objects

Example:
```python
# Get only non-minimized windows with thumbnails
sources = enum_screen_sources(
    thumbnail_size=Size(160, 120),
    external_flags=ScreenSourceFlags.IGNORE_SCREEN | ScreenSourceFlags.IGNORE_MINIMIZED
)
```

#### `create_snapshot(source_id: int, size: Size) -> Tuple[np.ndarray, Size]`

Creates a snapshot of the specified screen source.

- `source_id`: ID of the source to capture
- `size`: Requested size of the snapshot
- Returns: Tuple of (image data as numpy array, actual capture size)

Example:
```python
# Capture a window at 4K resolution
image, size = create_snapshot(window_id, Size(3840, 2160))
Image.fromarray(image, mode="RGB").save("4k_snapshot.png")
```

### Classes

#### `Size`

Represents a size with width and height.

```python
# Create a Full HD size
size = Size(width=1920, height=1080)
print(size)  # "1920x1080"

# Create a 4K UHD size
size_4k = Size(3840, 2160)
```

#### `Rect`

Represents a rectangle with left, top, right, and bottom coordinates.

```python
# Create a rectangle
rect = Rect(left=0, top=0, right=1920, bottom=1080)
print(rect)  # "(0, 0, 1920, 1080)"
print(rect.width)  # 1920
print(rect.height)  # 1080
```

#### `ScreenSourceInfo`

Contains information about a screen source.

Properties:
- `id`: Unique identifier
- `is_window`: Whether this is a window or display
- `rect`: Source rectangle
- `title`: Source title
- `process_path`: Process path (windows only)
- `is_minimized`: Window minimized state
- `is_maximized`: Window maximized state
- `is_primary`: Whether this is the primary display
- `icon_data`: Optional icon image data (numpy array)
- `thumbnail_data`: Optional thumbnail image data (numpy array)

Example:
```python
# Print detailed information about a source
def print_source_info(source):
    print(f"Source: {source.title}")
    print(f"Type: {'Window' if source.is_window else 'Display'}")
    print(f"Rectangle: {source.rect}")
    if source.is_window:
        print(f"Process: {source.process_path}")
        print(f"Minimized: {source.is_minimized}")
    else:
        print(f"Primary Display: {source.is_primary}")
```

#### `ScreenSourceFlags`

Enumeration flags for controlling screen source enumeration behavior.

```python
class ScreenSourceFlags(IntFlag):
    NONE = 0                        # Default behavior
    IGNORE_SCREEN = 1 << 0          # Ignore display screens
    IGNORE_WINDOW = 1 << 1          # Ignore windows
    IGNORE_MINIMIZED = 1 << 2       # Ignore minimized windows
    NOT_IGNORE_UNTITLED = 1 << 3    # Include untitled windows
    NOT_IGNORE_UNRESPONSIVE = 1 << 4  # Include unresponsive windows
    IGNORE_CURRENT_PROCESS_WINDOWS = 1 << 5  # Ignore windows from current process
    NOT_IGNORE_TOOLWINDOW = 1 << 6  # Include tool windows
    IGNORE_NOPROCESS_PATH = 1 << 7  # Ignore windows without process path
    NOT_SKIP_SYSTEM_WINDOWS = 1 << 8  # Include system windows
    NOT_SKIP_ZERO_LAYER_WINDOWS = 1 << 9  # Include zero layer windows
    ALL = 0xFFFFFFFF                # All flags enabled
```

Common flag combinations:
```python
# Get only displays (no windows)
displays = enum_screen_sources(
    external_flags=ScreenSourceFlags.IGNORE_WINDOW
)

# Get only active windows (no displays, no minimized)
active_windows = enum_screen_sources(
    external_flags=ScreenSourceFlags.IGNORE_SCREEN | 
                  ScreenSourceFlags.IGNORE_MINIMIZED
)

# Get all sources including system windows
all_sources = enum_screen_sources(
    external_flags=ScreenSourceFlags.NOT_SKIP_SYSTEM_WINDOWS | 
                  ScreenSourceFlags.NOT_IGNORE_TOOLWINDOW
)
```

## Examples

See the `examples` directory for more detailed examples:

- `basic_usage.py`: Demonstrates basic screen capture functionality
  - Enumerating screen sources
  - Selecting a source interactively
  - Capturing and saving screenshots
![Basic Usage Example](images/basic_usage.png)


- `enum_sources.py`: Shows advanced source enumeration with filtering
  - Using different flag combinations
  - Getting thumbnails and icons
  - Displaying detailed source information
  - Filtering sources by type and state
![Enum sources Example](images/enum_sources.png)

## Requirements

- Python 3.7+
- NumPy for array operations
