README.rst
1yaswfp
2======
3
4Yet Another SWF Parser.
5
6You can pronounce whatever you like :)
7
8
9How to use it
10-------------
11
12You can use ``swfparser.py`` as command line program or as a module.
13
14If you execute directly the usage is::
15
16 swfparser.py [-h] [-t] [-e] filepath
17
18 positional arguments:
19 filepath the SWF file to parse
20
21 optional arguments:
22 -h, --help show this help message and exit
23 -t, --show-tags show the first level tags of the file
24 -e, --extended show all objects with full detail and nested
25
26If you want to use it as a module, you can use the ``SWFParser`` class
27directly or the handy ``parsefile`` function::
28
29 >>> swf = swfparser.parsefile(<yourSWFfile>)
30 >>> swf.header
31 Header(name=Header, FileLength=4228, ...)
32 >>> len(swf.tags)
33 365
34 >>> swf.tags[0]
35 UnknownObject(name=SetBackgroundColor, raw_payload=b'\xff\xff\xff')
36 >>> swf.tags[3]
37 >>> obj = swf.tags[3]
38 >>> obj
39 PlaceObject2(name=PlaceObject2, CharacterId=1, ...)
40 >>> obj.CharacterId
41 1
42 >>> obj.Matrix.ScaleX
43 65536
44
45This follows the `SWF File Format Specification Version 19`_, but it is
46not (yet) 100% covered, so you may find some *unknown objects*.
47
48
49How to deal with still-unknown-objects
50--------------------------------------
51
52Not all the spec is covered (this is a work in progress!).
53
54When the parser finds a structure that still can't process (because more
55programming is needed), will just return an UnknownObject object with
56the unparsed bytes, or will raise an exception if you set
57the unknown_alert flag::
58
59 SWFParser.unknown_alert = True
60
61Add new structures to the parser is very simple. I'll be very glad to
62do it if you offer a real stream of bytes as an example or even
63a sample SWF file with the still missing object inside.
64
65
66Checking coverage
67-----------------
68
69There is an easy way of checking how many of the objects (tags, actions,
70structures, etc) are properly covered by the parser: just use the
71``coverage`` parameter::
72
73 $ python3 yaswfp/swfparser.py -c yaswfp/tests/samples/1252533834.swf
74 Header(Signature='CWS', ...)
75 Tags count: 55
76 Coverage is 97.3% of 74 total items
77 Most common parsed objects:
78 22 PlaceObject2
79 21 ShowFrame
80 10 LineStyleArray
81 Most common Unknown objects
82 2 DefineMorphShape2
83
84
85Development
86-----------
87
88To run the tests:
89
90 ./test
91
92You'll need ``python3-flake8`` and ``python3-nose``. Of course, this is
93Python 3.
94
95To complete some methods or be able to parse new structures, we should add
96examples that show that new stuff, see current "sanity" tests. Yes, unit tests
97are desirable, feel free to add those too.
98
99The project is hosted in GitHub::
100
101 https://github.com/facundobatista/yaswfp
102
103
104Contact
105-------
106
107Any doubt, any question, any suggestion, or whatever, feel free to open
108an issue in GitHub or find me in IRC, I'm ``facundobatista`` in Freenode.
109
110Thanks!
111
112
113.. _SWF File Format Specification Version 19: http://wwwimages.adobe.com/www.adobe.com/content/dam/Adobe/en/devnet/swf/pdf/swf-file-format-spec.pdf
114