StashPlayaVR API

[milindpatel63]

	Summary	A .NET Core API that provides a PlayaVR-compatible interface for StashApp, enabling VR video streaming and management.
	Repository	https://github.com/milindpatel63/stashplayavr

StashPlayaVR API

A .NET Core API that provides a PlayaVR-compatible interface for StashApp, enabling VR video streaming and management.

Features

• PlayaVR Compatibility: Full API compatibility with PlayaVR client applications
• Video Streaming: High-performance video streaming with range request support
• Authentication: JWT-based authentication with session support
• Image Processing: Automatic image resizing and SVG conversion for compatibility
• Docker Support: Ready-to-deploy Docker containerization
• Guest Access: Support for both authenticated and guest users
• Background Sync: Efficient data synchronization with StashApp

Prerequisites

• .NET 8.0 SDK
• Docker (optional)
• StashApp instance running and accessible

Installation

Option 1: Docker (Recommended)

1. Clone the repository:

git clone https://github.com/yourusername/stashplayavr-api.git
cd stashplayavr-api

2. Copy the example configuration:

cp src/appsettings.example.json src/appsettings.json

3. Edit src/appsettings.json with your StashApp details:

{
  "StashApp": {
    "Url": "http://your-stashapp-host:9999",
    "GraphQLUrl": "http://your-stashapp-host:9999/graphql",
    "ApiKey": "your-stash-api-key"
  },
  "JWT": {
    "Secret": "your-jwt-secret-key"
  },
  "Users": {
    "your-username": "your-password"
  }
}

4. Build and run with Docker:

docker build -t stashplayavr-api .
docker run -p 8890:8890 -v $(pwd)/src/appsettings.json:/app/appsettings.json stashplayavr-api

Option 2: Local Development

1. Clone the repository:

git clone https://github.com/yourusername/stashplayavr-api.git
cd stashplayavr-api

2. Copy the example configuration:

cp src/appsettings.example.json src/appsettings.json

3. Edit src/appsettings.json with your configuration

4. Restore dependencies and run:

dotnet restore src
dotnet run --project src

Configuration

Environment Variables

You can override configuration using environment variables:

export StashApp__Url="http://your-stashapp:9999"
export StashApp__ApiKey="your-api-key"
export JWT__Secret="your-jwt-secret"
export App__Port="8890"

JWT Secret Generation

Generate a secure JWT secret:

# Using OpenSSL
openssl rand -base64 64

# Using PowerShell
[System.Web.Security.Membership]::GeneratePassword(64, 0)

# Using Node.js
node -e "console.log(require('crypto').randomBytes(64).toString('base64'))"

API Endpoints

Authentication

• POST /api/playa/v2/auth/signin - User authentication
• POST /api/playa/v2/auth/refresh - Token refresh

Videos

• GET /api/playa/v2/videos - List videos with pagination
• GET /api/playa/v2/video/{id} - Get video details
• GET /api/playa/v2/video/{id}/stream - Stream video content
• GET /api/playa/v2/video/{id}/poster - Get video poster
• GET /api/playa/v2/video/{id}/preview - Get video preview

Categories & Metadata

• GET /api/playa/v2/categories - List categories/tags
• GET /api/playa/v2/actors - List actors/performers
• GET /api/playa/v2/studios - List studios

System

• GET /api/playa/v2/version - API version
• GET /api/playa/v2/configuration - Client configuration
• GET /api/playa/v2/health - Health check

Authentication

The API supports multiple authentication methods:

1. JWT Bearer Token: Standard Authorization header
2. Cookie Authentication: Session-based cookies
3. Query Parameter: ?auth_token=... for direct URLs
4. Guest Access: Limited access without authentication

Guest Access

Some endpoints support guest access with limited functionality:

• Categories return a dummy “Free” category
• Videos return empty results
• Posters and sprites work without authentication

Docker Deployment

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  stashplayavr-api:
    image: yourusername/stashplayavr-api:latest
    ports:
      - "8890:8890"
    environment:
      - StashApp__Url=http://your-stashapp:9999
      - StashApp__ApiKey=your-api-key
      - JWT__Secret=your-jwt-secret
    restart: unless-stopped

Health Checks

The Docker image includes health checks:

docker run --health-cmd="curl -f http://localhost:8890/api/playa/v2/health || exit 1" yourimage

Known Issues & Workarounds

PlayaVR Steam Client Categories Issue

Issue: Categories may not appear for logged-in users on PlayaVR Steam client.

Workaround: After logging in, restart the PlayaVR application to see all categories.

Technical Details: The PlayaVR Steam client has inconsistent authentication behavior - it only requests categories once during initial startup (when not logged in) and doesn’t re-request them after login. The API includes special handling to detect PlayaVR clients and return appropriate category data based on authentication status.