KingfisherWebP

https://github.com/yeatse/kingfisherwebp
Admin
KingfisherWebP is an extension for Kingfisher that adds WebP image format support with...
Tokens:4,533
Snippets:43
Trust Score:9.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install KingfisherWebP via Carthage

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Install KingfisherWebP and its dependencies (Kingfisher and libwebp-Xcode) using Carthage by adding the specified GitHub repositories to your Cartfile.

```shell
# Cartfile
github "yeatse/KingfisherWebP" ~> 1.4.0
github "onevcat/Kingfisher" ~> 7.0.0
github "SDWebImage/libwebp-Xcode" ~> 1.1.0
```

--------------------------------

### Install KingfisherWebP via CocoaPods

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Add 'KingfisherWebP' to your Podfile for installation using CocoaPods. This method automatically handles the libwebp dependency.

```ruby
# Podfile
pod 'KingfisherWebP'
```

--------------------------------

### Install KingfisherWebP via Swift Package Manager

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Add KingfisherWebP to your project using Swift Package Manager in Xcode 11 or later. Specify the repository URL to include the package.

```swift
dependencies: [
    .package(url: "https://github.com/yeatse/KingfisherWebP.git", from: "1.4.0")
]
```

--------------------------------

### Load Animated WebP with Preload Options

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Configure how animated WebP images are loaded and cached. Use `.preloadAllAnimationData` for smoother playback at the cost of higher memory usage, or omit it for on-demand frame decoding to save memory.

```swift
import Kingfisher
import KingfisherWebP

let animatedWebPUrl = URL(string: "https://example.com/animation.webp")!

// Load animated WebP with all frames preloaded (higher memory, smoother playback)
imageView.kf.setImage(
    with: animatedWebPUrl,
    options: [
        .processor(WebPProcessor.default),
        .cacheSerializer(WebPSerializer.default),
        .preloadAllAnimationData
    ]
)

// Load animated WebP with on-demand frame decoding (lower memory, may have frame drops)
imageView.kf.setImage(
    with: animatedWebPUrl,
    options: [
        .processor(WebPProcessor.default),
        .cacheSerializer(WebPSerializer.default)
    ]
)
```

--------------------------------

### Configure Custom Lossy WebP Compression

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Set custom lossy compression quality and other settings for WebP encoding. Ensure `KingfisherWebP` is imported.

```swift
import Kingfisher
import KingfisherWebP

// Create a custom serializer with lossy compression
var lossySerializer = WebPSerializer.default
lossySerializer.isLossy = true              // Enable lossy compression
lossySerializer.compressionQuality = 0.8    // 80% quality (0.0 to 1.0)
lossySerializer.originalDataUsed = false    // Force re-encoding

// Use custom serializer
imageView.kf.setImage(
    with: url,
    options: [
        .processor(WebPProcessor.default),
        .cacheSerializer(lossySerializer)
    ]
)
```

```swift
// Create a lossless serializer (default)
var losslessSerializer = WebPSerializer.default
losslessSerializer.isLossy = false          // Lossless compression
losslessSerializer.compressionQuality = 1.0 // Maximum quality
```

--------------------------------

### Configure HTTP Accept Header for WebP

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Add a request modifier to include the `image/webp */*` Accept header for servers that support content negotiation. This ensures WebP images are requested when available. Requires `Kingfisher` and `KingfisherWebP` imports.

```swift
import Kingfisher
import KingfisherWebP

// Create a request modifier to add WebP Accept header
let webpAcceptModifier = AnyModifier { request in
    var req = request
    req.addValue("image/webp */*", forHTTPHeaderField: "Accept")
    return req
}

// Add modifier to global defaults
KingfisherManager.shared.defaultOptions += [
    .requestModifier(webpAcceptModifier),
    .processor(WebPProcessor.default),
    .cacheSerializer(WebPSerializer.default)
]

// All requests now include WebP Accept header
imageView.kf.setImage(with: url)
```

--------------------------------

### Create Images from WebP Data using KingfisherWrapper

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Use `KingfisherWrapper<UIImage>.image` to create `UIImage` objects from WebP data. Allows control over image scale, and whether to load only the first frame or all frames for animated WebP. Requires `Kingfisher` and `KingfisherWebP` imports.

```swift
import Kingfisher
import KingfisherWebP

let webpData = try! Data(contentsOf: Bundle.main.url(forResource: "photo", withExtension: "webp")!)

// Create image with specific scale and single frame
if let image = KingfisherWrapper<UIImage>.image(
    webpData: webpData,
    scale: UIScreen.main.scale,
    onlyFirstFrame: false
) {
    imageView.image = image
}
```

```swift
// Create image with custom options
let options = ImageCreatingOptions(
    scale: 2.0,
    preloadAll: true,      // Preload all animation frames
    onlyFirstFrame: false  // Load all frames for animated WebP
)
if let animatedImage = KingfisherWrapper<UIImage>.image(webpData: webpData, options: options) {
    animatedImageView.image = animatedImage
}
```

--------------------------------

### Load WebP Image with WebPProcessor and WebPSerializer

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Load a WebP image using Kingfisher by explicitly setting the WebPProcessor and WebPSerializer in the options. This ensures WebP format is handled correctly for both processing and caching.

```swift
import Kingfisher
import KingfisherWebP

// Load a WebP image with explicit processor
let url = URL(string: "https://example.com/image.webp")!
imageView.kf.setImage(
    with: url,
    options: [
        .processor(WebPProcessor.default),
        .cacheSerializer(WebPSerializer.default)
    ]
)

// Access processor identifier for cache key purposes
let processor = WebPProcessor.default
print(processor.identifier) // "com.yeatse.WebPProcessor"
```

--------------------------------

### Set Default WebP Options for KingfisherManager

Source: https://github.com/yeatse/kingfisherwebp/blob/main/README.md

Configure KingfisherManager with default WebP processor and serializer options to handle WebP images seamlessly across all Kingfisher operations. This simplifies integration by setting it once.

```swift
KingfisherManager.shared.defaultOptions += [
  .processor(WebPProcessor.default),
  .cacheSerializer(WebPSerializer.default)
]
```

--------------------------------

### Add Accept Header for WebP Images

Source: https://github.com/yeatse/kingfisherwebp/blob/main/README.md

Include the 'image/webp */*' Accept header in Kingfisher requests to inform servers that WebP format is supported. This is necessary for some image servers that require this header.

```swift
let modifier = AnyModifier { request in
    var req = request
    req.addValue("image/webp */*", forHTTPHeaderField: "Accept")
    return req
}

KingfisherManager.shared.defaultOptions += [
    .requestModifier(modifier),
    // ... other options
]
```

--------------------------------

### Access Frames from Animated WebP using WebPFrameSource

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Allows on-demand access to individual frames of an animated WebP image without loading the entire animation into memory. Useful for custom animation handling. Requires Kingfisher and KingfisherWebP imports.

```swift
import Kingfisher
import KingfisherWebP

let webpData = try! Data(contentsOf: animatedWebPURL)

// Process to get image with frame source (don't preload all frames)
let processor = WebPProcessor.default
let options = KingfisherParsedOptionsInfo([]) // No preloadAllAnimationData
guard let image = processor.process(item: .data(webpData), options: options),
      let frameSource = image.kf.frameSource else {
    return
}

// Access frame source properties
print("Total frames: \(frameSource.frameCount)")

// Get frames on demand
for index in 0..<frameSource.frameCount {
    // Get frame CGImage
    if let cgImage = frameSource.frame(at: index, maxSize: nil) {
        let frameImage = UIImage(cgImage: cgImage)
        print("Frame \(index): \(frameImage.size)")
    }

    // Get frame duration
    let duration = frameSource.duration(at: index)
    print("Frame \(index) duration: \(duration) seconds")
}

// Get scaled frame (useful for thumbnails)
let maxSize = CGSize(width: 100, height: 100)
if let scaledFrame = frameSource.frame(at: 0, maxSize: maxSize) {
    let thumbnail = UIImage(cgImage: scaledFrame)
    print("Scaled frame size: \(scaledFrame.width)x\(scaledFrame.height)")
}
```

--------------------------------

### Set WebP Processor and Serializer for Kingfisher

Source: https://github.com/yeatse/kingfisherwebp/blob/main/README.md

Use WebPProcessor and WebPSerializer with Kingfisher to handle WebP images from network. This is useful when you need to display WebP images using Kingfisher.

```swift
let url = URL(string: "url_of_your_webp_image")
imageView.kf.setImage(with: url, options: [.processor(WebPProcessor.default), .cacheSerializer(WebPSerializer.default)])
```

--------------------------------

### WebPSerializer for WebP Cache Serialization

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Utilize WebPSerializer to manage WebP image caching with Kingfisher's disk cache. It handles storing original WebP data and deserializing it when loading from cache, falling back to default behavior for non-WebP formats.

```swift
import Kingfisher
import KingfisherWebP

// Use WebPSerializer for caching WebP images
let url = URL(string: "https://example.com/photo.webp")!
imageView.kf.setImage(
    with: url,
    options: [
        .processor(WebPProcessor.default),
        .cacheSerializer(WebPSerializer.default)
    ]
)

// The serializer will:
// 1. Store the original WebP data to disk cache
// 2. Deserialize WebP data back to image when loading from cache
// 3. Fall back to default serializer for non-WebP formats
```

--------------------------------

### Convert Animated Image to Animated WebP

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Encodes an animated UIImage (like a GIF) into the animated WebP format, preserving frame durations. Requires Kingfisher and KingfisherWebP imports.

```swift
import Kingfisher
import KingfisherWebP

// Load an animated GIF as UIImage
let gifData = try! Data(contentsOf: Bundle.main.url(forResource: "animation", withExtension: "gif")!)
let animatedImage = KingfisherWrapper<UIImage>.animatedImage(data: gifData, options: .init())!

// Convert animated image to WebP
if let animatedWebP = animatedImage.kf.webpRepresentation(isLossy: false, quality: 75.0) {
    print("Animated WebP size: \(animatedWebP.count) bytes")
    try? animatedWebP.write(to: outputURL)
}
```

--------------------------------

### Manually Serialize and Deserialize WebP Images

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Encode `UIImage` to WebP data for custom caching or network transfer, and decode WebP data back to `UIImage`. Requires `Kingfisher` and `KingfisherWebP` imports.

```swift
import Kingfisher
import KingfisherWebP

let serializer = WebPSerializer.default

// Encode an image to WebP data for storage
let image = UIImage(named: "photo")!
if let webpData = serializer.data(with: image, original: nil) {
    // Store webpData to custom cache or send over network
    try? webpData.write(to: cacheURL)
    print("Image encoded to WebP: \(webpData.count) bytes")
}

// Decode WebP data back to image
let cachedData = try! Data(contentsOf: cacheURL)
let options = KingfisherParsedOptionsInfo([])
if let cachedImage = serializer.image(with: cachedData, options: options) {
    imageView.image = cachedImage
}
```

--------------------------------

### Convert UIImage/NSImage to WebP Data

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Converts an image to WebP data with options for lossless or lossy compression and custom quality settings. Ensure KingfisherWebP is imported.

```swift
import Kingfisher
import KingfisherWebP

let image = UIImage(named: "photo")!

// Convert to lossless WebP (default)
if let losslessWebP = image.kf.webpRepresentation() {
    print("Lossless WebP size: \(losslessWebP.count) bytes")
    try? losslessWebP.write(to: outputURL)
}

// Convert to lossy WebP with custom quality
if let lossyWebP = image.kf.webpRepresentation(isLossy: true, quality: 75.0) {
    print("Lossy WebP (75%) size: \(lossyWebP.count) bytes")
}

// Convert with maximum quality lossy (quality range: 0.0 to 100.0)
if let highQualityWebP = image.kf.webpRepresentation(isLossy: true, quality: 100.0) {
    print("High quality lossy WebP size: \(highQualityWebP.count) bytes")
}
```

--------------------------------

### Set Global Defaults for WebP Processing

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Configure Kingfisher to automatically use WebP processing and serialization for all image requests. Add `.processor(WebPProcessor.default)` and `.cacheSerializer(WebPSerializer.default)` to `KingfisherManager.shared.defaultOptions`. This is typically done in `AppDelegate`.

```swift
import Kingfisher
import KingfisherWebP

// Set WebP support as global default (typically in AppDelegate)
KingfisherManager.shared.defaultOptions += [
    .processor(WebPProcessor.default),
    .cacheSerializer(WebPSerializer.default)
]

// Now all Kingfisher calls automatically support WebP
imageView.kf.setImage(with: webpUrl)  // WebP works automatically
imageView.kf.setImage(with: jpegUrl)  // Non-WebP also works (falls back to default)
```

```swift
// Additional global options for animated WebP
KingfisherManager.shared.defaultOptions += [
    .processor(WebPProcessor.default),
    .cacheSerializer(WebPSerializer.default),
    .preloadAllAnimationData  // Preload all animation frames
]
```

--------------------------------

### Detect WebP Image Format from Data

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Checks if a given Data object represents a WebP image using the `isWebPFormat` extension. This is useful for conditional processing. Requires KingfisherWebP import.

```swift
import KingfisherWebP

let imageData = try! Data(contentsOf: imageURL)

// Check if data is WebP format
if imageData.isWebPFormat {
    print("This is a WebP image")
    // Process with WebPProcessor
    let processor = WebPProcessor.default
    let image = processor.process(item: .data(imageData), options: .init([]))
} else {
    print("This is not a WebP image")
    // Process with default processor
    let image = DefaultImageProcessor.default.process(item: .data(imageData), options: .init([]))
}

// WebP detection checks for RIFF and WEBP headers
// Requires at least 12 bytes of data
let tooShortData = Data([0x00, 0x01])
print(tooShortData.isWebPFormat) // false
```

--------------------------------

### Process Raw WebP Data Directly

Source: https://context7.com/yeatse/kingfisherwebp/llms.txt

Decode WebP data programmatically without using Kingfisher's network layer. This is useful for processing WebP data loaded from local files or other sources.

```swift
import Kingfisher
import KingfisherWebP

// Load WebP data from file or network
let webpData = try! Data(contentsOf: Bundle.main.url(forResource: "image", withExtension: "webp")!)

// Process the data into an image
let processor = WebPProcessor.default
let options = KingfisherParsedOptionsInfo([])
if let image = processor.process(item: .data(webpData), options: options) {
    imageView.image = image
    print("WebP image decoded successfully")
    print("Frame count: \(image.kf.imageFrameCount ?? 1)")
}

// Process with first frame only (for animated WebP)
let firstFrameOptions = KingfisherParsedOptionsInfo([.onlyLoadFirstFrame])
if let stillImage = processor.process(item: .data(webpData), options: firstFrameOptions) {
    thumbnailView.image = stillImage
}
```
Tokens:
Raw