Skip to content

Commit 621e0f1

Browse files
fulldecentfulldecent
committed
Clearly show the public API
1 parent 7ff57c8 commit 621e0f1

File tree

3 files changed

+1013
-901
lines changed

3 files changed

+1013
-901
lines changed

‎README.md‎

Lines changed: 64 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,56 @@
11
# FDWaveformView
22

3-
FDWaveformView is an easy way to display an audio waveform in your app. It is a nice visualization to show a playing audio file or to select a position in a file.
3+
FDWaveformView displays audio waveforms in Swift apps so users can preview audio, scrub, and pick positions with ease.
44

5-
Usage
6-
-----
5+
## Usage
76

8-
To use it, add an `FDWaveformView` using Interface Builder or programmatically and then just load your audio as per this example. Note: if your audio file does not have file extension, see <a href="https://stackoverflow.com/questions/9290972/is-it-possible-to-make-avurlasset-work-without-a-file-extension">this SO question</a>.
7+
Add an `FDWaveformView` in Interface Builder or programmatically, then load audio. If your file is missing an extension, see the [Stack Overflow answer on AVURLAsset without extensions](https://stackoverflow.com/questions/9290972/is-it-possible-to-make-avurlasset-work-without-a-file-extension).
98

109
```swift
1110
let thisBundle = Bundle(for: type(of: self))
1211
let url = thisBundle.url(forResource: "Submarine", withExtension: "aiff")
1312
self.waveform.audioURL = url
1413
```
1514

16-
<p align="center">
17-
<img src="https://i.imgur.com/5N7ozog.png" width=250>
18-
</p>
15+
![Waveform overview showing loaded audio](https://i.imgur.com/5N7ozog.png)
1916

20-
Features
21-
--------
17+
## Features
2218

23-
**Set play progress** to highlight part of the waveform:
19+
### Highlight playback
20+
21+
Highlight a portion of the waveform to show progress.
2422

2523
```swift
2624
self.waveform.highlightedSamples = 0..<(self.waveform.totalSamples / 2)
2725
```
2826

29-
<p align="center">
30-
<img src="https://i.imgur.com/fRrHiRP.png" width=250>
31-
</p>
27+
![Waveform with highlighted progress](https://i.imgur.com/fRrHiRP.png)
28+
29+
### Zoom for detail
3230

33-
**Zoom in** to show only part of the waveform, of course, zooming in will smoothly re-render to show progressively more detail:
31+
Render only the visible portion while progressively adding detail as you zoom.
3432

3533
```swift
3634
self.waveform.zoomSamples = 0..<(self.waveform.totalSamples / 4)
3735
```
3836

39-
<p align="center">
40-
<img src="https://i.imgur.com/JQOKQ3o.png" width=250>
41-
</p>
37+
![Zoomed waveform segment](https://i.imgur.com/JQOKQ3o.png)
4238

43-
**Enable gestures** for zooming in, panning around or scrubbing:
39+
### Gesture control
40+
41+
Allow scrubbing, stretching, and scrolling with built-in gestures.
4442

4543
```swift
4644
self.waveform.doesAllowScrubbing = true
4745
self.waveform.doesAllowStretch = true
4846
self.waveform.doesAllowScroll = true
4947
```
5048

51-
<p align="center">
52-
<img src="https://i.imgur.com/8oR7cpq.gif" width=250 loop=infinite>
53-
</p>
49+
![Gesture-driven waveform interaction](https://i.imgur.com/8oR7cpq.gif)
50+
51+
### Animated updates
5452

55-
**Supports animation** for changing properties:
53+
Animate property changes for smoother UI feedback.
5654

5755
```swift
5856
UIView.animate(withDuration: 0.3) {
@@ -61,25 +59,60 @@ UIView.animate(withDuration: 0.3) {
6159
}
6260
```
6361

64-
<p align="center">
65-
<img src="https://i.imgur.com/EgxXaCY.gif" width=250 loop=infinite>
66-
</p>
62+
![Animated waveform highlight change](https://i.imgur.com/EgxXaCY.gif)
63+
64+
### Rendering quality
65+
66+
- Antialiased waveforms draw extra pixels to avoid jagged edges.
67+
- Autolayout-driven size changes trigger re-rendering to prevent pixelation.
68+
- Supports iOS 12+ and Swift 5.
69+
- Includes unit tests running on GitHub Actions.
70+
71+
## Installation
6772

68-
Creates **antialiased waveforms** by drawing more pixels than are seen on screen. Also, if you resize me (autolayout) I will render more detail if necessary to avoid pixelation.
73+
Use Swift Package Manager: in Xcode choose File > Swift Packages > Add Package Dependency and point to this repository. Legacy installation options are available if needed.
6974

70-
Supports **iOS12+** and Swift 5.
75+
## API
7176

72-
**Includes unit tests**, now running on GitHub Actions
77+
Following is the complete API for this module:
78+
79+
- `FDWaveformView` (open class, subclass of `UIView`)
80+
- `init()` (public init) default initializer
81+
- `delegate: FDWaveformViewDelegate?` (open var, get/set) delegate for loading and rendering callbacks
82+
- `audioURL: URL?` (open var, get/set) audio file to render asynchronously
83+
- `totalSamples: Int` (open var, get) sample count of the loaded asset
84+
- `highlightedSamples: CountableRange<Int>?` (open var, get/set) range tinted with `progressColor`
85+
- `zoomSamples: CountableRange<Int>` (open var, get/set) range currently displayed
86+
- `doesAllowScrubbing: Bool` (open var, get/set) enable tap and pan scrubbing
87+
- `doesAllowStretch: Bool` (open var, get/set) enable pinch-to-zoom
88+
- `doesAllowScroll: Bool` (open var, get/set) enable panning across the waveform
89+
- `wavesColor: UIColor` (open var, get/set) tint for the base waveform image
90+
- `progressColor: UIColor` (open var, get/set) tint for the highlighted waveform
91+
- `loadingInProgress: Bool` (open var, get) indicates async load in progress
92+
93+
- `FDWaveformViewDelegate` (@objc public protocol)
94+
- `waveformViewWillRender(_ waveformView: FDWaveformView)` (optional)
95+
- `waveformViewDidRender(_ waveformView: FDWaveformView)` (optional)
96+
- `waveformViewWillLoad(_ waveformView: FDWaveformView)` (optional)
97+
- `waveformViewDidLoad(_ waveformView: FDWaveformView)` (optional)
98+
- `waveformDidBeginPanning(_ waveformView: FDWaveformView)` (optional)
99+
- `waveformDidEndPanning(_ waveformView: FDWaveformView)` (optional)
100+
- `waveformDidEndScrubbing(_ waveformView: FDWaveformView)` (optional)
101+
102+
A couple other things are exposed that we do not consider public API:
103+
104+
- `FDWaveformView` (implements `UIGestureRecognizerDelegate`)
105+
- `gestureRecognizer(_:shouldRecognizeSimultaneouslyWith:) -> Bool`
73106

74107
## Testing
75108

76-
To build and run tests from the command line, first find an available simulator:
109+
Find an available simulator:
77110

78111
```sh
79112
xcrun simctl list devices available | grep iPhone
80113
```
81114

82-
Then build and test using a simulator ID (replace the placeholder with an ID from the output above):
115+
Build and test using a simulator ID from the output:
83116

84117
```sh
85118
# Build the library
@@ -93,10 +126,6 @@ cd Example
93126
xcodebuild build -scheme Example -destination 'id=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
94127
```
95128

96-
## Installation
97-
98-
Add this to your project using Swift Package Manager. In Xcode that is simply: File > Swift Packages > Add Package Dependency... and you're done. Alternative installations options are shown below for legacy projects.
99-
100129
## Contributing
101130

102-
* This project's layout is based on <https://github.com/fulldecent/swift6-module-template>
131+
- This project's layout is based on <https://github.com/fulldecent/swift6-module-template>

0 commit comments

Comments
 (0)