# react-native-wallpapers

A comprehensive React Native library for Android wallpaper management. Set static, live (GIF), video, and 3D parallax wallpapers with full customization — blur, brightness, color filters, crop, auto-rotation, and more.

> **Android only.** iOS does not support programmatic wallpaper setting.

---

## Installation

```sh
npm install react-native-wallpapers
```

Then rebuild your Android app:

```sh
cd android && ./gradlew clean && cd ..
npx react-native run-android
```

### Register the package manually (if not using auto-linking)

In `android/app/src/main/java/.../MainApplication.kt`:

```kotlin
import com.rnwallpapers.RNWallpapersPackage

override fun getPackages(): List<ReactPackage> = listOf(
    MainReactPackage(),
    RNWallpapersPackage(),  // ← add this
)
```

### Add WorkManager dependency (required for Auto Change)

In `android/app/build.gradle`:

```gradle
dependencies {
    implementation "androidx.work:work-runtime-ktx:2.9.0"
}
```

---

## Permissions

Add to your app's `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.SET_WALLPAPER" />
<uses-permission android:name="android.permission.INTERNET" />

<!-- For saving wallpapers to gallery -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
  android:maxSdkVersion="28" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
```

---

## Quick Start

```ts
import {
  setWallpaper,
  WallpaperTarget,
  WallpaperType,
  ColorFilter,
} from 'react-native-wallpapers';

// Set a static wallpaper on home screen
await setWallpaper('https://example.com/image.jpg');

// Set on both screens
await setWallpaper('https://example.com/image.jpg', {
  target: WallpaperTarget.BOTH,
});
```

---

## API Reference

### `setWallpaper(source, options?)`

The main function. Sets a wallpaper from a URL or local file path.

```ts
const result = await setWallpaper(source, options);
// result.success → boolean
// result.error   → { code, message } if failed
```

| Parameter | Type | Description |
|---|---|---|
| `source` | `string` | Remote URL or local `file://` path |
| `options` | `SetWallpaperOptions` | Customization options (see below) |

#### SetWallpaperOptions

| Option | Type | Default | Description |
|---|---|---|---|
| `target` | `WallpaperTarget` | `HOME` | Where to set: HOME, LOCK, BOTH |
| `type` | `WallpaperType` | `STATIC` | STATIC, LIVE, VIDEO, PARALLAX |
| `fit` | `WallpaperFit` | `FILL` | FILL, FIT, STRETCH, CENTER, TILE |
| `blurRadius` | `number` | `0` | Blur amount 0–25 |
| `brightness` | `number` | `0` | -1.0 (dark) to 1.0 (bright) |
| `opacity` | `number` | `1.0` | 0.0 to 1.0 |
| `colorFilter` | `ColorFilterOptions` | — | Apply color overlay |
| `crop` | `CropOptions` | — | Crop before setting |
| `parallax` | `ParallaxOptions` | — | 3D parallax settings |
| `video` | `VideoWallpaperOptions` | — | Video playback settings |
| `live` | `LiveWallpaperOptions` | — | GIF playback settings |

---

### Shorthand Functions

```ts
// Home screen only
await setHomeWallpaper(source, options);

// Lock screen only
await setLockWallpaper(source, options);

// Both screens
await setBothWallpapers(source, options);

// Different wallpapers for each screen
await setDualWallpaper(homeSource, lockSource, options);
```

---

### `downloadWallpaper(url, options?)`

Download a wallpaper to device storage.

```ts
const result = await downloadWallpaper('https://example.com/image.jpg', {
  filename: 'my_wallpaper',
  saveDirectory: 'Pictures/MyApp',
  showNotification: true,
});

console.log(result.filePath);  // /storage/emulated/0/Pictures/MyApp/my_wallpaper.jpg
console.log(result.fileSize);  // size in bytes
```

---

### `startAutoChange(options)`

Automatically rotate wallpapers on a schedule using WorkManager (persists across app restarts).

```ts
await startAutoChange({
  sources: [
    'https://example.com/1.jpg',
    'https://example.com/2.jpg',
    'https://example.com/3.jpg',
  ],
  intervalMinutes: 60,   // every 1 hour
  target: WallpaperTarget.HOME,
  shuffle: true,
});
```

### `stopAutoChange()`

```ts
await stopAutoChange();
```

### `getAutoChangeStatus()`

```ts
const status = await getAutoChangeStatus();
// status.isActive      → boolean
// status.currentIndex  → number
// status.totalSources  → number
// status.intervalMinutes → number
```

---

### `clearWallpaper(target?)`

Reset to system default wallpaper.

```ts
await clearWallpaper(WallpaperTarget.BOTH);
```

---

### `getDeviceCapabilities()`

Check what the device supports before enabling advanced features.

```ts
const caps = await getDeviceCapabilities();

if (caps.supportsVideoWallpaper) {
  // show video wallpaper option
}
if (caps.supportsParallax) {
  // show parallax option
}

console.log(caps.screenWidth, caps.screenHeight);
```

---

### `onWallpaperChanged(listener)`

Listen for wallpaper change events.

```ts
const unsubscribe = onWallpaperChanged((event) => {
  console.log('Changed:', event.target, event.type, event.timestamp);
});

// Cleanup
unsubscribe();
```

---

## Examples

### Live GIF Wallpaper

```ts
await setWallpaper('https://example.com/animated.gif', {
  type: WallpaperType.LIVE,
  target: WallpaperTarget.HOME,
  live: {
    speed: 1.2,
    loopCount: 0, // infinite
  },
});
```

### 3D Parallax Wallpaper

```ts
await setWallpaper('https://example.com/image.jpg', {
  type: WallpaperType.PARALLAX,
  parallax: {
    intensity: 0.7,
    useGyroscope: true,
    maxOffset: 40,
  },
});
```

### Video Wallpaper

```ts
await setWallpaper('https://example.com/video.mp4', {
  type: WallpaperType.VIDEO,
  video: {
    loop: true,
    muted: true,
    speed: 1.0,
    startTime: 2, // start at 2 seconds
  },
});
```

### With Color Filter + Blur

```ts
await setWallpaper('https://example.com/image.jpg', {
  target: WallpaperTarget.BOTH,
  blurRadius: 8,
  colorFilter: {
    type: ColorFilter.DARK,
    intensity: 0.4,
  },
  brightness: -0.1,
});
```

### Error Handling

```ts
import { WallpaperError } from 'react-native-wallpapers';

const result = await setWallpaper('https://example.com/image.jpg');

if (!result.success) {
  switch (result.error?.code) {
    case WallpaperError.PERMISSION_DENIED:
      console.log('No permission to set wallpaper');
      break;
    case WallpaperError.DOWNLOAD_FAILED:
      console.log('Could not download image');
      break;
    case WallpaperError.FILE_NOT_FOUND:
      console.log('File does not exist');
      break;
    default:
      console.log('Error:', result.error?.message);
  }
}
```

---

## Enums

```ts
WallpaperTarget  → HOME | LOCK | BOTH
WallpaperType    → STATIC | LIVE | VIDEO | PARALLAX
WallpaperFit     → FILL | FIT | STRETCH | CENTER | TILE
ColorFilter      → NONE | WARM | COOL | DARK | LIGHT | GRAYSCALE | SEPIA | VINTAGE
WallpaperError   → PERMISSION_DENIED | FILE_NOT_FOUND | UNSUPPORTED_FORMAT | SET_FAILED | DOWNLOAD_FAILED | UNKNOWN
```

---

## Android Version Support

| Feature | Min Android |
|---|---|
| Static wallpaper | Android 5.0 (API 21) |
| Lock screen wallpaper | Android 7.0 (API 24) |
| Video wallpaper | Android 8.0 (API 26) |
| Live/GIF wallpaper | Android 5.0 (API 21) |
| Parallax wallpaper | Android 5.0 (API 21) |
| Auto-change (WorkManager) | Android 5.0 (API 21) |

---

## License

MIT