{"id":1435,"url":"https://github.com/onevcat/APNGKit","last_synced_at":"2025-08-06T13:32:48.308Z","repository":{"id":1213779,"uuid":"41801057","full_name":"onevcat/APNGKit","owner":"onevcat","description":"High performance and delightful way to play with APNG format in iOS.","archived":false,"fork":false,"pushed_at":"2024-03-19T14:45:26.000Z","size":5256,"stargazers_count":2196,"open_issues_count":6,"forks_count":200,"subscribers_count":49,"default_branch":"master","last_synced_at":"2024-07-22T05:42:46.036Z","etag":null,"topics":["apng","apng-image","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onevcat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"onevcat"}},"created_at":"2015-09-02T12:56:57.000Z","updated_at":"2024-07-13T23:24:42.000Z","dependencies_parsed_at":"2024-03-18T15:37:37.068Z","dependency_job_id":"f07e5557-d392-4484-a6d3-a71fa87a2716","html_url":"https://github.com/onevcat/APNGKit","commit_stats":{"total_commits":416,"total_committers":22,"mean_commits":18.90909090909091,"dds":"0.11538461538461542","last_synced_commit":"995386261326bce7ff19879cac84b6f27ce35629"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onevcat%2FAPNGKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onevcat%2FAPNGKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onevcat%2FAPNGKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onevcat%2FAPNGKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onevcat","download_url":"https://codeload.github.com/onevcat/APNGKit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215780271,"owners_count":15929791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apng","apng-image","swift"],"created_at":"2024-01-05T20:15:46.408Z","updated_at":"2024-08-17T16:30:53.667Z","avatar_url":"https://github.com/onevcat.png","language":"Swift","funding_links":["https://github.com/sponsors/onevcat"],"categories":["Media","Libs","Swift","Images [🔝](#readme)","iOS"],"sub_categories":["GIF","Images","Other free courses","APNGKit"],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/1019875/139824374-c83a0d99-7ef6-4497-b980-ee3e3ad7565e.png\" alt=\"APNGKit\" title=\"APNGKit\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://swift.org/package-manager/\"\u003e\u003cimg src=\"https://img.shields.io/badge/SPM-supported-DE5C43.svg?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"http://cocoadocs.org/docsets/APNGKit\"\u003e\u003cimg src=\"https://img.shields.io/cocoapods/v/APNGKit.svg?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Carthage/Carthage/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"https://raw.githubusercontent.com/onevcat/APNGKit/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/cocoapods/l/APNGKit.svg?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/cocoapods/p/APNGKit.svg?style=flat\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/made%20with-%3C3-blue.svg\"\u003e\n\u003c/p\u003e\n\nAPNGKit is a high performance framework for loading and displaying APNG images in iOS and macOS. It's built with \nhigh-level abstractions and brings a delightful API. Since be that, you will feel at home and joy when using APNGKit to \nplay with images in APNG format.\n\n## APNG, what and why?\n\nThe [Animated Portable Network Graphics (APNG)](https://en.wikipedia.org/wiki/APNG) is a file format extending the \nwell-known PNG format. It allows for animated PNG files that work similarly to animated GIF files, while supporting \n24-bit images and 8-bit transparency not available for GIFs. This means much better quality of animation. At the same \ntime, the file size is comparable to or even less than, if created carefully, GIFs.\n\nTalk is cheap; show me the image. You can click on the image to see how it looks like when animating.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"http://apng.onevcat.com/demo\" target=\"_blank\"\u003e\u003cimg src=\"https://github.com/onevcat/APNGKit/blob/dcc79f3f5f0e06bf571b88b8078017693d7a16ac/images/demo.png?raw=true\" alt=\"APNGKit Demo\" title=\"APNGKit Demo\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nThat's cool. APNG is much better! But wait...why haven't I heard about APNG before? It is not a popular format, so why \nshould I use it in my next great iOS/macOS app?\n\nGood question! APNG is an excellent extension for regular PNG, and it is also very simple to use and not conflicting \nwith current PNG standard (It consists a standard PNG header, so if your platform does not support APNG, it will be \nrecognized as a normal PNG with its first frame being displayed as a static image). But unfortunately, it is a rebel \nformat so that it is not accepted by the PNG group. However, it is accepted by many vendors and is even mentioned in \n[W3C Standards](http://www.w3.org/TR/html5/embedded-content-0.html#the-img-element). There is another format called \nMNG (Multiple-image Network Graphics), which is created by the same team as PNG. It is a comprehensive format, but very \nvery very (重要的事要说三遍) complex. It is so complex that despite being a \"standard\", it was almost universally rejected.\nThere is only one \"popular\" browser called [Konqueror](https://konqueror.org)(at least I have used it before when I was \nin high school) that supports MNG, which is really a sad but reasonable story.\n\nEven though APNG is not accepted currently, we continue to see the widespread implementation of it. Apple recently \nsupported APNG in both [desktop and mobile Safari](http://www.macrumors.com/2014/09/28/ios-8-safari-supports-animated-png-images/). \nMicrosoft Edge and Chrome are also considering adding APNG support since it is already officially added in \n[WebKit core](https://bugs.webkit.org/show_bug.cgi?id=17022).\n\nAPNG is such a nice format to bring users much better experience of animating images. The more APNG is used, the more \nrecognition and support it will get. Not only in the browsers world, but also in the apps we always love. That's why \nI created this framework.\n\n## Installation\n\n### Requirement\n\niOS 9.0+ / macOS 10.11+ / tvOS 9.0+\n\n### Swift Package Manager\n\nThe **recommended way** to install APNGKit is to use Swift Package Manager. Adding it to your project with Xcode:\n\n- File \u003e Swift Packages \u003e Add Package Dependency\n- Add https://github.com/onevcat/APNGKit.git\n- Select \"Up to Next Major\" with \"2.0.0\"\n\n### CocoaPods\n\n[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects.\n\n```bash\n$ gem install cocoapods\n```\n\nTo integrate APNGKit into your Xcode project using CocoaPods, specify it in your `Podfile`:\n\n```ruby\nsource 'https://github.com/CocoaPods/Specs.git'\nplatform :ios, '9.0'\nuse_frameworks!\n\ntarget 'your_app' do\n  pod 'APNGKit', '~\u003e 2.0'\nend\n```\n\nThen, run the following command:\n\n```bash\n$ pod install\n```\n\nYou should open the `{Project}.xcworkspace` instead of the `{Project}.xcodeproj` after you installed anything from CocoaPods.\n\nFor more information about how to use CocoaPods, I suggest [this tutorial](http://www.raywenderlich.com/64546/introduction-to-cocoapods-2).\n\n## Usage\n\n### Basic\n\nImport APNGKit into your source files in which you want to use the framework.\n\n```swift\nimport APNGKit\n```\n\n#### Load an APNG Image\n\n```swift\n// Load an APNG image from file in main bundle\nvar image = try APNGImage(named: \"your_image\")\n\n// Or\n// Load an APNG image from file at specified path\nif let url = Bundle.main.url(forResource: \"your_image\", withExtension: \"apng\") {\n    image = try APNGImage(fileURL: path)\n}\n\n// Or\n// Load an APNG image from data\nlet data: Data = ... // From disk or network or anywhere else.\nimage = try APNGImage(data: data)\n```\n\nYou may notice that all initializers are throwable. If anything is wrong during creating the image, it let you know the \nerror explicitly and you have a chance to handle it. We will cover the error handling soon later.\n\n#### Display an APNG Image\n\nWhen you have an `APNGImage` object, you can use it to initialize an image view and display it on screen with an \n`APNGImageView`, which is a subclass of `UIView` or `NSView`:\n\n```swift\nlet image: APNGImage = ... // You already have an APNG image object.\n\nlet imageView = APNGImageView(image: image)\nview.addSubview(imageView)\n```\n\n#### Start animation\n\nThe animation will be played automatically as soon as the image view is created with a valid APNG image. If you do not\nwant the animation to be played automatically, set the `autoStartAnimationWhenSetImage` property to `false` before you \nassign an image:\n\n```swift\nlet imageView = APNGImageView(frame: .zero)\nimageView.autoStartAnimationWhenSetImage = false\nimageView.image = image\n\n// Start the animation manually:\nimageView.startAnimating()\n```\n\n#### XIB or Storyboard\n\nIf you are an Interface Builder lover, drag a `UIView` (or `NSView`) (Please note, not a `UIImageView` or `NSImageView`) \nto the canvas, and modify its class to `APNGImageView`. Then, you can drag an `IBOutlet` and play with it as usual, such\nas setting its `image` property.\n\n\n### Delegates\n\nAPNG defines the play loop count as `numberOfPlays` in `APNGImage`, and APNGKit respects it by default. To inspect the \nend of each loop, register yourself as a delegate of `APNGImageView.onOnePlayDone`:\n\n```swift\nclass ViewController: UIViewController {\n    override func viewDidLoad() {\n        super.viewDidLoad()\n\n        let imageView = APNGImageView(image: image)\n        imageView.onOnePlayDone.delegate(on: self) { (self, count) in\n            print(\"Played: \\(count)\")\n        }\n    }\n}\n```\n\nWhen `numberOfPlays` is `nil`, the animation will be played forever. If it is a limited non-zero value, the animation \nwill be stopped at the final frame when the loop count reaches the limit. To inspect the whole animation is done, \nuse `onAllPlaysDone`:\n\n```swift\nimageView.onAllPlaysDone.delegate(on: self) { (self, _) in\n    print(\"All done.\")\n}\n```\n\nAPNGKit loads the data in a streaming way by default, it reads the frame information while playing the animation. Since\nAPNG encodes the duration in each frame, it is not possible to get the whole animation duration before loading all frames \ninformation. Before the first reading pass finishes, you can only get a partial duration for loaded frames. To get the\nfull duration, use `APNGImage.onFramesInformationPrepared`:\n\n```swift\nlet image = try APNGImage(named: \"image\")\nimage.onFramesInformationPrepared.delegate(on: self) { (self, _) in\n    switch image.duration {\n        case .full(let duration):\n            print(\"Full duration: \\(duration)\")\n        case .partial:\n            print(\"This should not happen.\")\n    }\n}\n\nimageView.image = image\n```\n\nOr, you can specify the `.fullFirstPass` option while creating the `APNGImage`. It reads all frames before starting \nrendering and animating the image:\n\n```swift\nlet image = try APNGImage(named: \"image\", options: [.fullFirstPass])\nprint(image.duration) // .full(duration)\n```\n\nAPNGKit provides a few other reading options. Please let me skip it for now and you can check them in documentation.\n\n### Error handling\n\n#### While creating image\n\nCreating an `APNGImage` can throw an error if anything goes wrong. All possible errors while decoding are defined as an\n`APNGKitError.decoderError`. When an error happens while creating the image, you are expected to check if it should be \ntreated as a normal static image. If so, try to set it as the static image:\n\n```swift\ndo {\n    let image = try APNGImage(named: data.imageName)\n    imageView.image = image\n} catch {\n    if let normalImage = error.apngError?.normalImage {\n        imageView.staticImage = normalImage\n    } else {\n        print(\"Error: \\(error)\")\n    }\n}\n```\n\n#### While playing animation\n\nIf some frames are broken, the default image defined in APNG should be displayed as a fallback. You can get this in \nAPNGKit for free. To get notified when this happens, listen to `APNGImageView.onFallBackToDefaultImage`:\n\n```swift\nimageView.onDecodingFrameError.delegate(on: self) { (self, error) in\n    print(\"A frame cannot be decoded. After this, either onFallBackToDefaultImage or onFallBackToDefaultImageFailed happens.\")\n}\n\nimageView.onFallBackToDefaultImage.delegate(on: self) { (self, _) in\n    print(\"Fall back to default image.\")\n}\nimageView.onFallBackToDefaultImageFailed.delegate(on: self) { (self, error) in\n    print(\"Tried to fall back to default image, but it fails: \\(error)\")\n}\n```\n\n### PNG compression\n\nXcode will compress all PNG files in your app bundle when you build the project. Since APNG is an extension format of \nPNG, Xcode will think there are redundancy data in that file and compress it into a single static image. When this happens,\nyou may inspect a log message from APNGKit:\n\n\u003e `CgBI` chunk found. It seems that the input image is compressed by Xcode and not supported by APNGKit. \n\u003e Consider to rename it to `apng` to prevent compressing.\n\nUsually this is not what you want when working with APNG. You can disable the PNG compression by setting \n\"COMPRESS_PNG_FILES\" to NO in the build settings of your app target. However, it will also prevent Xcode to optimize \nyour other regular PNGs. \n\nA better approach would be renaming your APNG files with an extension besides of \"png\". If you do so, Xcode will stop \nrecognizing your APNG files as PNG format, and will not apply compression on them. A suggested extension is \"apng\", \nwhich will be detected and handled by APNGKit seamlessly.\n\n## Acknowledgement\n\nThe demo elephant image in README file is stolen from ICS Lab, you can find the original post [here](http://ics-web.jp/lab/archives/2441).\n\n## Reference\n\nIf you are interested in APNG, you can know more about it from the links below (some of them are written in Chinese).\n\n* [APNG Specification](https://wiki.mozilla.org/APNG_Specification)\n* [APNG - Wikipedia](https://www.google.co.jp/url?sa=t\u0026rct=j\u0026q=\u0026esrc=s\u0026source=web\u0026cd=2\u0026cad=rja\u0026uact=8\u0026ved=0CCkQFjABahUKEwjYxdSQjtrHAhWIn5QKHVDkAHs\u0026url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FAPNG\u0026usg=AFQjCNF2CJ-OePHGKIhR14TdrCuEn9nn1A\u0026sig2=188CAiDHZv0FVn7QVnhVVQ)\n* [小牛犊 APNG 力挫老古董 MNG](http://blog.wuxinan.net/archives/313)\n* [再回眸，丽影如初](http://isux.tencent.com/introduction-of-apng.html)\n\nAPNGKit can only load and display APNG image now. The creating feature will be developed later. If you need to create APNG file now, I suggest using [iSparta](http://isparta.github.io) or [apngasm](http://apngasm.sourceforge.net) instead for now.\n\n## License\n\nAPNGKit is released under the MIT license. See LICENSE for details.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonevcat%2FAPNGKit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonevcat%2FAPNGKit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonevcat%2FAPNGKit/lists"}